sondera-harness 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

sondera/__init__.py

@@ -1,28 +1,44 @@
-"""Sondera SDK for Python - Agent governance and policy enforcement.
+"""Sondera Harness - Steer agents with rules, not prompts.
 
-This SDK provides tools for integrating AI agents with the Sondera Platform
-for policy enforcement, guardrails, and governance.
+Wrap your agent, write Cedar policies, ship with confidence. When a policy
+denies an action, the agent gets the reason why and adjusts. Agents self-correct
+instead of failing. This is steering, not just blocking.
 
-Main Components:
-    - Harness: Abstract base class for harness implementations
-    - RemoteHarness: Production harness connecting to Sondera Platform
-    - CedarPolicyEngine: Local policy-as-code engine using Cedar
+Same input, same verdict. Rules are deterministic, not probabilistic. Stop
+debugging prompts and start writing policies.
+
+Why Sondera Harness:
+    - Steer, don't just block: Denied actions include explanations
+    - Drop-in integration: Native middleware for LangGraph, ADK, Strands
+    - Full observability: Trajectories capture every action and decision
+    - Deterministic rules: Same input, same verdict, every time
+    - Ship faster: Reliability, safety, security, and compliance built in
+
+Harness Implementations:
+    - CedarPolicyHarness: Local evaluation, no network calls, no dependencies
+    - SonderaRemoteHarness: Team policies, dashboards, centralized audit logs
 
 Framework Integrations:
-    - sondera.langgraph: LangGraph/LangChain middleware
+    - sondera.langgraph: LangGraph middleware
     - sondera.adk: Google ADK plugin
-    - sondera.strands: Strands Agent SDK hook
+    - sondera.strands: Strands lifecycle hooks
 
 Example:
-    >>> from sondera import SonderaRemoteHarness, Agent
-    >>> harness = SonderaRemoteHarness(sondera_api_key="<YOUR_SONDERA_API_KEY>")
+    >>> from sondera import CedarPolicyHarness, Agent, Tool
+    >>> from sondera.harness.cedar.schema import agent_to_cedar_schema
+    >>>
     >>> agent = Agent(
     ...     id="my-agent",
-    ...     provider_id="langchain",
-    ...     name="My Agent",
+    ...     provider_id="local",
+    ...     name="My_Agent",
     ...     description="A helpful assistant",
-    ...     instruction="Be helpful and concise",
-    ...     tools=[],
+    ...     instruction="Help users with tasks",
+    ...     tools=[Tool(name="Bash", description="Run commands", parameters=[])],
+    ... )
+    >>> policy = "permit(principal, action, resource);"
+    >>> harness = CedarPolicyHarness(
+    ...     policy_set=policy,
+    ...     schema=agent_to_cedar_schema(agent),
     ... )
     >>> await harness.initialize(agent=agent)
 """
@@ -47,10 +63,12 @@ from sondera.types import (
     AdjudicatedStep,
     AdjudicatedTrajectory,
     Adjudication,
+    AdjudicationRecord,
     Agent,
     Content,
     Decision,
     Parameter,
+    PolicyAnnotation,
     PolicyEngineMode,
     PromptContent,
     Role,
@@ -93,6 +111,8 @@ __all__ = [
     "Adjudication",
     "AdjudicatedStep",
     "AdjudicatedTrajectory",
+    "AdjudicationRecord",
+    "PolicyAnnotation",
     "Decision",
     # Exceptions
     "SonderaError",

sondera/adk/plugin.py

@@ -64,7 +64,7 @@ class SonderaHarnessPlugin(BasePlugin):
         plugin = SonderaHarnessPlugin(harness=harness)
 
         # Create agent and runner with the plugin
-        agent = Agent(name="my-agent", model="gemini-2.0-flash", ...)
+        agent = Agent(name="my-agent", model="gemini-2.5-flash", ...)
         runner = Runner(
             agent=agent,
             app_name="my-app",

sondera/harness/cedar/harness.py

@@ -23,6 +23,7 @@ from sondera.types import (
     Agent,
     Content,
     Decision,
+    PolicyAnnotation,
     PromptContent,
     Role,
     Stage,
@@ -69,6 +70,7 @@ class CedarPolicyHarness(AbstractHarness):
         *,
         policy_set: PolicySet | str,
         schema: CedarSchema,
+        agent: Agent | None = None,
         logger: logging.Logger | None = None,
     ):
         """Initialize the Cedar policy engine.
@@ -77,12 +79,13 @@ class CedarPolicyHarness(AbstractHarness):
             policy_set: Cedar policies to evaluate. Can be a PolicySet instance
                 or Cedar policy text. Required.
             schema: Cedar schema generated from agent_to_cedar_schema(). Required.
+            agent: The agent to govern. Required for adjudication.
             logger: Logger instance.
 
         Raises:
             ValueError: If policy_set or schema is not provided.
         """
-        self._agent: Agent | None = None
+        self._agent: Agent | None = agent
         self._trajectory_id: str | None = None
         self._trajectory_step_count: int = 0
         self._logger = logger or _LOGGER
@@ -101,6 +104,16 @@ class CedarPolicyHarness(AbstractHarness):
             self._policy_set = PolicySet(policy_set)
         else:
             self._policy_set = policy_set
+
+        for policy in self._policy_set.policies():
+            annotations = policy.annotations()
+            if "escalate" in annotations and str(policy.effect()) != "Forbid":
+                policy_id = annotations.get("id", policy.id())
+                raise ValueError(
+                    f"Policy '{policy_id}' has @escalate but is not a forbid policy. "
+                    "@escalate is only valid on forbid policies."
+                )
+
         # Extract namespace name from schema
         namespaces = list(schema.root.keys())
         if namespaces:
@@ -110,6 +123,8 @@ class CedarPolicyHarness(AbstractHarness):
             raise ValueError("Schema must have at least one namespace")
         # Authorizer will be initialized with entities when agent is set
         self._authorizer: Authorizer | None = None
+        # Cache for pre-parsed tool response schemas (tool_name -> parsed schema dict)
+        self._tool_response_schemas: dict[str, dict[str, object]] = {}
 
     def _build_authorizer(self) -> Authorizer:
         """Build the Cedar authorizer with current entities."""
@@ -128,8 +143,9 @@ class CedarPolicyHarness(AbstractHarness):
         if self._agent:
             agent_uid = EntityUid(f"{self._namespace}::Agent", self._agent.id)
 
-            # Add tool entities from agent's tools
+            # Add tool entities from agent's tools and pre-parse response schemas
             tool_entities: list[EntityUid] = []
+            self._tool_response_schemas = {}
             for tool in self._agent.tools:
                 tool_id = tool.id or tool.name
                 tool_uid = EntityUid(f"{self._namespace}::Tool", tool_id)
@@ -142,6 +158,11 @@ class CedarPolicyHarness(AbstractHarness):
                 )
                 tool_entities.append(tool_uid)
                 entities.append(tool_entity)
+                # Pre-parse response JSON schema for use in _tool_response
+                if tool.response_json_schema:
+                    self._tool_response_schemas[tool.name] = json.loads(
+                        tool.response_json_schema
+                    )
 
             agent_entity = Entity(
                 agent_uid,
@@ -252,11 +273,47 @@ class CedarPolicyHarness(AbstractHarness):
         assert request is not None, "Unexpected none request"
         response = self._authorizer.is_authorized(request, self._policy_set)
         if str(response.decision) == "Allow":
-            reason = f"Allowed by policies: {response.reason}"
-            return Adjudication(decision=Decision.ALLOW, reason=reason)
+            return Adjudication(
+                decision=Decision.ALLOW,
+                reason=f"Allowed by policies: {response.reason}",
+            )
+
+        annotations: list[PolicyAnnotation] = []
+        hard_deny_ids = []
+        for internal_id in response.reason:
+            policy = self._policy_set.policy(internal_id)
+            if policy is None:
+                raise RuntimeError(f"Policy '{internal_id}' not found in policy set")
+            policy_annotations = policy.annotations()
+            if "escalate" not in policy_annotations:
+                hard_deny_ids.append(internal_id)
+            else:
+                custom = {
+                    k: v
+                    for k, v in policy_annotations.items()
+                    if k not in ("id", "reason", "escalate")
+                }
+                annotations.append(
+                    PolicyAnnotation(
+                        id=policy_annotations.get("id", internal_id),
+                        description=policy_annotations.get("reason", ""),
+                        escalate=True,
+                        escalate_arg=policy_annotations["escalate"],
+                        custom=custom,
+                    )
+                )
+
+        if not hard_deny_ids and annotations:
+            return Adjudication(
+                decision=Decision.ESCALATE,
+                reason=f"Escalated by policies: {response.reason}",
+                annotations=annotations,
+            )
         else:
-            reason = f"Denied by policies: {response.reason}"
-            return Adjudication(decision=Decision.DENY, reason=reason)
+            return Adjudication(
+                decision=Decision.DENY,
+                reason=f"Denied by policies: {hard_deny_ids}",
+            )
 
     def _message_request(
         self,
@@ -311,11 +368,17 @@ class CedarPolicyHarness(AbstractHarness):
         action_name = tool_id.replace(" ", "_").replace("-", "_")
         action_uid = EntityUid(f"{self._namespace}::Action", action_name)
 
-        context = Context(
-            {"parameters_json": json.dumps(content.args), "parameters": content.args},
-            schema=self._schema,
-            action=action_uid,
-        )
+        # Build context - only include typed parameters if schema defines them
+        context_data: dict[str, object] = {
+            "parameters_json": json.dumps(content.args),
+        }
+        # Check if tool has typed parameters schema
+        if self._agent:
+            tool = next((t for t in self._agent.tools if t.name == tool_id), None)
+            if tool and tool.parameters_json_schema:
+                context_data["parameters"] = content.args
+
+        context = Context(context_data, schema=self._schema, action=action_uid)
 
         return Request(
             principal=agent_uid,
@@ -345,14 +408,22 @@ class CedarPolicyHarness(AbstractHarness):
         action_name = tool_id.replace(" ", "_").replace("-", "_")
         action_uid = EntityUid(f"{self._namespace}::Action", action_name)
 
-        context = Context(
-            {
-                "response_json": json.dumps(content.response, default=str),
-                "response": content.response,
-            },
-            schema=self._schema,
-            action=action_uid,
-        )
+        # Build context - only include typed response if schema defines it
+        context_data: dict[str, object] = {
+            "response_json": json.dumps(content.response, default=str),
+        }
+        # Check if tool has typed response schema (pre-parsed in _build_authorizer)
+        if tool_id in self._tool_response_schemas:
+            response_schema = self._tool_response_schemas[tool_id]
+            # Check if the response schema is a simple type (not object/Record)
+            # Simple types get wrapped in {"value": ...} by the schema generator
+            if response_schema.get("type") not in ["object", "OBJECT"]:
+                # Simple type was wrapped in {"value": ...} by schema generator
+                context_data["response"] = {"value": content.response}
+            else:
+                context_data["response"] = content.response
+
+        context = Context(context_data, schema=self._schema, action=action_uid)
 
         return Request(
             principal=agent_uid,

sondera/harness/sondera/_grpc.py

@@ -11,13 +11,16 @@ from sondera.types import (
     Adjudication,
     AdjudicationRecord,
     Agent,
+    Check,
     Content,
     Decision,
+    GuardrailContext,
     Parameter,
     PolicyAnnotation,
     PolicyEngineMode,
     PromptContent,
     Role,
+    SourceCode,
     Stage,
     Tool,
     ToolRequestContent,
@@ -81,6 +84,38 @@ def _convert_sdk_content_to_pb(content: Content) -> primitives_pb2.Content:
         raise ValueError(f"Unsupported content type: {type(content)}")
 
 
+def _convert_sdk_tool_to_pb(tool: Tool) -> primitives_pb2.Tool:
+    """Convert SDK Tool to protobuf Tool."""
+    pb_params = [
+        primitives_pb2.Parameter(
+            name=param.name,
+            description=param.description,
+            type=param.type,
+        )
+        for param in tool.parameters
+    ]
+
+    pb_source = (
+        primitives_pb2.SourceCode(
+            language=tool.source.language,
+            code=tool.source.code,
+        )
+        if tool.source
+        else None
+    )
+
+    return primitives_pb2.Tool(
+        id=tool.id,
+        name=tool.name,
+        description=tool.description,
+        parameters=pb_params,
+        parameters_json_schema=tool.parameters_json_schema,
+        response=tool.response,
+        response_json_schema=tool.response_json_schema,
+        source=pb_source,
+    )
+
+
 def _convert_pb_adjudication_to_sdk(
     adjudication: primitives_pb2.Adjudication,
 ) -> Adjudication:
@@ -95,8 +130,8 @@ def _convert_pb_adjudication_to_sdk(
     # Convert annotations
     annotations = [
         PolicyAnnotation(
-            id=ann.id,
-            description=ann.description,
+            id=ann.id if ann.HasField("id") else "",
+            description=ann.description if ann.HasField("description") else "",
             custom=dict(ann.custom),
         )
         for ann in adjudication.annotations
@@ -105,6 +140,7 @@ def _convert_pb_adjudication_to_sdk(
     return Adjudication(
         decision=decision_map[adjudication.decision],
         reason=adjudication.reason,
+        policy_ids=list(adjudication.policy_ids),
         annotations=annotations,
     )
 
@@ -117,13 +153,33 @@ def _convert_pb_agent_to_sdk(pb_agent: primitives_pb2.Agent) -> Agent:
             Parameter(name=p.name, description=p.description, type=p.type)
             for p in pb_tool.parameters
         ]
+
+        # Handle optional source field
+        source = None
+        if pb_tool.HasField("source"):
+            source = SourceCode(
+                language=pb_tool.source.language,
+                code=pb_tool.source.code,
+            )
+
         tools.append(
             Tool(
-                id=None,  # Protobuf Tool message doesn't have an id field
+                id=pb_tool.id if pb_tool.HasField("id") else None,
                 name=pb_tool.name,
                 description=pb_tool.description,
                 parameters=params,
-                response=pb_tool.response if pb_tool.response else None,
+                parameters_json_schema=(
+                    pb_tool.parameters_json_schema
+                    if pb_tool.HasField("parameters_json_schema")
+                    else None
+                ),
+                response=pb_tool.response if pb_tool.HasField("response") else None,
+                response_json_schema=(
+                    pb_tool.response_json_schema
+                    if pb_tool.HasField("response_json_schema")
+                    else None
+                ),
+                source=source,
             )
         )
 
@@ -266,11 +322,28 @@ def _convert_pb_adjudicated_step_to_sdk(
         raise ValueError("AdjudicatedStep must have an adjudication field")
     adjudication = _convert_pb_adjudication_to_sdk(pb_adjudication)
 
+    # Convert guardrails
+    guardrails = None
+    if pb_adjudicated_step.HasField("guardrails"):
+        checks = {}
+        for name, pb_check in pb_adjudicated_step.guardrails.checks.items():
+            checks[name] = Check(
+                name=pb_check.name,
+                flagged=pb_check.flagged,
+                message=pb_check.message if pb_check.HasField("message") else None,
+            )
+        guardrails = GuardrailContext(checks=checks)
+
     # Default mode to GOVERN since protobuf doesn't have this field
     # In practice, this should be set based on the policy engine configuration
     mode = PolicyEngineMode.GOVERN
 
-    return AdjudicatedStep(mode=mode, adjudication=adjudication, step=trajectory_step)
+    return AdjudicatedStep(
+        mode=mode,
+        adjudication=adjudication,
+        step=trajectory_step,
+        guardrails=guardrails,
+    )
 
 
 def _convert_pb_trajectory_to_sdk(

sondera/harness/sondera/harness.py

@@ -24,6 +24,7 @@ from sondera.harness.sondera._grpc import (
     _convert_sdk_content_to_pb,
     _convert_sdk_role_to_pb,
     _convert_sdk_stage_to_pb,
+    _convert_sdk_tool_to_pb,
     _convert_sdk_trajectory_status_to_pb,
 )
 from sondera.proto.sondera.core.v1 import primitives_pb2
@@ -337,24 +338,8 @@ class SonderaRemoteHarness(AbstractHarness):
             AuthenticationError: If authentication fails
             grpc.RpcError: If other gRPC error occurs
         """
-        # Convert SDK agent to protobuf tools
-        pb_tools = []
-        for tool in agent.tools:
-            pb_params = []
-            for param in tool.parameters:
-                pb_params.append(
-                    primitives_pb2.Parameter(
-                        name=param.name, description=param.description, type=param.type
-                    )
-                )
-
-            pb_tool = primitives_pb2.Tool(
-                name=tool.name,
-                description=tool.description,
-                parameters=pb_params,
-                response=tool.response,
-            )
-            pb_tools.append(pb_tool)
+        # Convert SDK agent tools to protobuf
+        pb_tools = [_convert_sdk_tool_to_pb(tool) for tool in agent.tools]
 
         request = harness_pb2.RegisterAgentRequest(
             provider_id=agent.provider_id,

sondera/proto/sondera/core/v1/primitives_pb2.py

@@ -26,7 +26,7 @@ from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2
 from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n sondera/core/v1/primitives.proto\x12\x0fsondera.core.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1fgoogle/protobuf/timestamp.proto\",\n\nSourceCode\x12\x10\n\x08language\x18\x01 \x01(\t\x12\x0c\n\x04\x63ode\x18\x02 \x01(\t\"<\n\tParameter\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12\x0c\n\x04type\x18\x03 \x01(\t\"\xba\x01\n\x04Tool\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12.\n\nparameters\x18\x03 \x03(\x0b\x32\x1a.sondera.core.v1.Parameter\x12\x15\n\x08response\x18\x04 \x01(\tH\x00\x88\x01\x01\x12\x30\n\x06source\x18\x05 \x01(\x0b\x32\x1b.sondera.core.v1.SourceCodeH\x01\x88\x01\x01\x42\x0b\n\t_responseB\t\n\x07_source\"\x86\x01\n\x05\x41gent\x12\n\n\x02id\x18\x01 \x01(\t\x12\x13\n\x0bprovider_id\x18\x02 \x01(\t\x12\x0c\n\x04name\x18\x03 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x04 \x01(\t\x12\x13\n\x0binstruction\x18\x05 \x01(\t\x12$\n\x05tools\x18\x06 \x03(\x0b\x32\x15.sondera.core.v1.Tool\"\x16\n\x06Prompt\x12\x0c\n\x04text\x18\x01 \x01(\t\"D\n\x0bToolRequest\x12\x0f\n\x07tool_id\x18\x01 \x01(\t\x12$\n\x04\x61rgs\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value\"I\n\x0cToolResponse\x12\x0f\n\x07tool_id\x18\x01 \x01(\t\x12(\n\x08response\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value\"\xb2\x01\n\x07\x43ontent\x12)\n\x06prompt\x18\x01 \x01(\x0b\x32\x17.sondera.core.v1.PromptH\x00\x12\x34\n\x0ctool_request\x18\x02 \x01(\x0b\x32\x1c.sondera.core.v1.ToolRequestH\x00\x12\x36\n\rtool_response\x18\x03 \x01(\x0b\x32\x1d.sondera.core.v1.ToolResponseH\x00\x42\x0e\n\x0c\x63ontent_type\"\xb7\x01\n\x0eTrajectoryStep\x12%\n\x05stage\x18\x01 \x01(\x0e\x32\x16.sondera.core.v1.Stage\x12#\n\x04role\x18\x02 \x01(\x0e\x32\x15.sondera.core.v1.Role\x12.\n\ncreated_at\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12)\n\x07\x63ontent\x18\x04 \x01(\x0b\x32\x18.sondera.core.v1.Content\"\xf7\x03\n\nTrajectory\x12\n\n\x02id\x18\x01 \x01(\t\x12\x10\n\x08\x61gent_id\x18\x02 \x01(\t\x12\x31\n\x06status\x18\x03 \x01(\x0e\x32!.sondera.core.v1.TrajectoryStatus\x12;\n\x08metadata\x18\x04 \x03(\x0b\x32).sondera.core.v1.Trajectory.MetadataEntry\x12.\n\ncreated_at\x18\x05 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12.\n\nupdated_at\x18\x06 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x33\n\nstarted_at\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x88\x01\x01\x12\x31\n\x08\x65nded_at\x18\x08 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12.\n\x05steps\x18\t \x03(\x0b\x32\x1f.sondera.core.v1.TrajectoryStep\x1aG\n\rMetadataEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12%\n\x05value\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value:\x02\x38\x01\x42\r\n\x0b_started_atB\x0b\n\t_ended_at\"H\n\x05\x43heck\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07\x66lagged\x18\x02 \x01(\x08\x12\x14\n\x07message\x18\x03 \x01(\tH\x00\x88\x01\x01\x42\n\n\x08_message\"\x98\x01\n\x10GuardrailContext\x12=\n\x06\x63hecks\x18\x01 \x03(\x0b\x32-.sondera.core.v1.GuardrailContext.ChecksEntry\x1a\x45\n\x0b\x43hecksEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12%\n\x05value\x18\x02 \x01(\x0b\x32\x16.sondera.core.v1.Check:\x02\x38\x01\"\xc4\x01\n\x11PolicyAnnotations\x12\x0f\n\x02id\x18\x01 \x01(\tH\x00\x88\x01\x01\x12\x18\n\x0b\x64\x65scription\x18\x02 \x01(\tH\x01\x88\x01\x01\x12>\n\x06\x63ustom\x18\x03 \x03(\x0b\x32..sondera.core.v1.PolicyAnnotations.CustomEntry\x1a-\n\x0b\x43ustomEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x42\x05\n\x03_idB\x0e\n\x0c_description\"\x98\x01\n\x0c\x41\x64judication\x12+\n\x08\x64\x65\x63ision\x18\x01 \x01(\x0e\x32\x19.sondera.core.v1.Decision\x12\x0e\n\x06reason\x18\x02 \x01(\t\x12\x12\n\npolicy_ids\x18\x03 \x03(\t\x12\x37\n\x0b\x61nnotations\x18\x04 \x03(\x0b\x32\".sondera.core.v1.PolicyAnnotations\"\xac\x01\n\x0f\x41\x64judicatedStep\x12-\n\x04step\x18\x01 \x01(\x0b\x32\x1f.sondera.core.v1.TrajectoryStep\x12\x35\n\nguardrails\x18\x02 \x01(\x0b\x32!.sondera.core.v1.GuardrailContext\x12\x33\n\x0c\x61\x64judication\x18\x03 \x01(\x0b\x32\x1d.sondera.core.v1.Adjudication\"y\n\x15\x41\x64judicatedTrajectory\x12/\n\ntrajectory\x18\x01 \x01(\x0b\x32\x1b.sondera.core.v1.Trajectory\x12/\n\x05steps\x18\x02 \x03(\x0b\x32 .sondera.core.v1.AdjudicatedStep*\xd3\x01\n\x10TrajectoryStatus\x12!\n\x1dTRAJECTORY_STATUS_UNSPECIFIED\x10\x00\x12\x1d\n\x19TRAJECTORY_STATUS_PENDING\x10\x01\x12\x1d\n\x19TRAJECTORY_STATUS_RUNNING\x10\x02\x12\x1f\n\x1bTRAJECTORY_STATUS_COMPLETED\x10\x03\x12\x1f\n\x1bTRAJECTORY_STATUS_SUSPENDED\x10\x04\x12\x1c\n\x18TRAJECTORY_STATUS_FAILED\x10\x05*\x99\x01\n\x05Stage\x12\x15\n\x11STAGE_UNSPECIFIED\x10\x00\x12\x11\n\rSTAGE_PRE_RUN\x10\x01\x12\x13\n\x0fSTAGE_PRE_MODEL\x10\x02\x12\x14\n\x10STAGE_POST_MODEL\x10\x03\x12\x12\n\x0eSTAGE_PRE_TOOL\x10\x04\x12\x13\n\x0fSTAGE_POST_TOOL\x10\x05\x12\x12\n\x0eSTAGE_POST_RUN\x10\x06*[\n\x04Role\x12\x14\n\x10ROLE_UNSPECIFIED\x10\x00\x12\r\n\tROLE_USER\x10\x01\x12\x0e\n\nROLE_MODEL\x10\x02\x12\r\n\tROLE_TOOL\x10\x03\x12\x0f\n\x0bROLE_SYSTEM\x10\x04*b\n\x08\x44\x65\x63ision\x12\x18\n\x14\x44\x45\x43ISION_UNSPECIFIED\x10\x00\x12\x12\n\x0e\x44\x45\x43ISION_ALLOW\x10\x01\x12\x11\n\rDECISION_DENY\x10\x02\x12\x15\n\x11\x44\x45\x43ISION_ESCALATE\x10\x03\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n sondera/core/v1/primitives.proto\x12\x0fsondera.core.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1fgoogle/protobuf/timestamp.proto\",\n\nSourceCode\x12\x10\n\x08language\x18\x01 \x01(\t\x12\x0c\n\x04\x63ode\x18\x02 \x01(\t\"<\n\tParameter\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12\x0c\n\x04type\x18\x03 \x01(\t\"\xce\x02\n\x04Tool\x12\x0f\n\x02id\x18\x06 \x01(\tH\x00\x88\x01\x01\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12.\n\nparameters\x18\x03 \x03(\x0b\x32\x1a.sondera.core.v1.Parameter\x12#\n\x16parameters_json_schema\x18\x07 \x01(\tH\x01\x88\x01\x01\x12\x15\n\x08response\x18\x04 \x01(\tH\x02\x88\x01\x01\x12!\n\x14response_json_schema\x18\x08 \x01(\tH\x03\x88\x01\x01\x12\x30\n\x06source\x18\x05 \x01(\x0b\x32\x1b.sondera.core.v1.SourceCodeH\x04\x88\x01\x01\x42\x05\n\x03_idB\x19\n\x17_parameters_json_schemaB\x0b\n\t_responseB\x17\n\x15_response_json_schemaB\t\n\x07_source\"\x86\x01\n\x05\x41gent\x12\n\n\x02id\x18\x01 \x01(\t\x12\x13\n\x0bprovider_id\x18\x02 \x01(\t\x12\x0c\n\x04name\x18\x03 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x04 \x01(\t\x12\x13\n\x0binstruction\x18\x05 \x01(\t\x12$\n\x05tools\x18\x06 \x03(\x0b\x32\x15.sondera.core.v1.Tool\"\x16\n\x06Prompt\x12\x0c\n\x04text\x18\x01 \x01(\t\"D\n\x0bToolRequest\x12\x0f\n\x07tool_id\x18\x01 \x01(\t\x12$\n\x04\x61rgs\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value\"I\n\x0cToolResponse\x12\x0f\n\x07tool_id\x18\x01 \x01(\t\x12(\n\x08response\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value\"\xb2\x01\n\x07\x43ontent\x12)\n\x06prompt\x18\x01 \x01(\x0b\x32\x17.sondera.core.v1.PromptH\x00\x12\x34\n\x0ctool_request\x18\x02 \x01(\x0b\x32\x1c.sondera.core.v1.ToolRequestH\x00\x12\x36\n\rtool_response\x18\x03 \x01(\x0b\x32\x1d.sondera.core.v1.ToolResponseH\x00\x42\x0e\n\x0c\x63ontent_type\"\xb7\x01\n\x0eTrajectoryStep\x12%\n\x05stage\x18\x01 \x01(\x0e\x32\x16.sondera.core.v1.Stage\x12#\n\x04role\x18\x02 \x01(\x0e\x32\x15.sondera.core.v1.Role\x12.\n\ncreated_at\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12)\n\x07\x63ontent\x18\x04 \x01(\x0b\x32\x18.sondera.core.v1.Content\"\xf7\x03\n\nTrajectory\x12\n\n\x02id\x18\x01 \x01(\t\x12\x10\n\x08\x61gent_id\x18\x02 \x01(\t\x12\x31\n\x06status\x18\x03 \x01(\x0e\x32!.sondera.core.v1.TrajectoryStatus\x12;\n\x08metadata\x18\x04 \x03(\x0b\x32).sondera.core.v1.Trajectory.MetadataEntry\x12.\n\ncreated_at\x18\x05 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12.\n\nupdated_at\x18\x06 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x33\n\nstarted_at\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x88\x01\x01\x12\x31\n\x08\x65nded_at\x18\x08 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12.\n\x05steps\x18\t \x03(\x0b\x32\x1f.sondera.core.v1.TrajectoryStep\x1aG\n\rMetadataEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12%\n\x05value\x18\x02 \x01(\x0b\x32\x16.google.protobuf.Value:\x02\x38\x01\x42\r\n\x0b_started_atB\x0b\n\t_ended_at\"H\n\x05\x43heck\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07\x66lagged\x18\x02 \x01(\x08\x12\x14\n\x07message\x18\x03 \x01(\tH\x00\x88\x01\x01\x42\n\n\x08_message\"\x98\x01\n\x10GuardrailContext\x12=\n\x06\x63hecks\x18\x01 \x03(\x0b\x32-.sondera.core.v1.GuardrailContext.ChecksEntry\x1a\x45\n\x0b\x43hecksEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12%\n\x05value\x18\x02 \x01(\x0b\x32\x16.sondera.core.v1.Check:\x02\x38\x01\"\xc4\x01\n\x11PolicyAnnotations\x12\x0f\n\x02id\x18\x01 \x01(\tH\x00\x88\x01\x01\x12\x18\n\x0b\x64\x65scription\x18\x02 \x01(\tH\x01\x88\x01\x01\x12>\n\x06\x63ustom\x18\x03 \x03(\x0b\x32..sondera.core.v1.PolicyAnnotations.CustomEntry\x1a-\n\x0b\x43ustomEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\x42\x05\n\x03_idB\x0e\n\x0c_description\"\x98\x01\n\x0c\x41\x64judication\x12+\n\x08\x64\x65\x63ision\x18\x01 \x01(\x0e\x32\x19.sondera.core.v1.Decision\x12\x0e\n\x06reason\x18\x02 \x01(\t\x12\x12\n\npolicy_ids\x18\x03 \x03(\t\x12\x37\n\x0b\x61nnotations\x18\x04 \x03(\x0b\x32\".sondera.core.v1.PolicyAnnotations\"\xac\x01\n\x0f\x41\x64judicatedStep\x12-\n\x04step\x18\x01 \x01(\x0b\x32\x1f.sondera.core.v1.TrajectoryStep\x12\x35\n\nguardrails\x18\x02 \x01(\x0b\x32!.sondera.core.v1.GuardrailContext\x12\x33\n\x0c\x61\x64judication\x18\x03 \x01(\x0b\x32\x1d.sondera.core.v1.Adjudication\"y\n\x15\x41\x64judicatedTrajectory\x12/\n\ntrajectory\x18\x01 \x01(\x0b\x32\x1b.sondera.core.v1.Trajectory\x12/\n\x05steps\x18\x02 \x03(\x0b\x32 .sondera.core.v1.AdjudicatedStep*\xd3\x01\n\x10TrajectoryStatus\x12!\n\x1dTRAJECTORY_STATUS_UNSPECIFIED\x10\x00\x12\x1d\n\x19TRAJECTORY_STATUS_PENDING\x10\x01\x12\x1d\n\x19TRAJECTORY_STATUS_RUNNING\x10\x02\x12\x1f\n\x1bTRAJECTORY_STATUS_COMPLETED\x10\x03\x12\x1f\n\x1bTRAJECTORY_STATUS_SUSPENDED\x10\x04\x12\x1c\n\x18TRAJECTORY_STATUS_FAILED\x10\x05*\x99\x01\n\x05Stage\x12\x15\n\x11STAGE_UNSPECIFIED\x10\x00\x12\x11\n\rSTAGE_PRE_RUN\x10\x01\x12\x13\n\x0fSTAGE_PRE_MODEL\x10\x02\x12\x14\n\x10STAGE_POST_MODEL\x10\x03\x12\x12\n\x0eSTAGE_PRE_TOOL\x10\x04\x12\x13\n\x0fSTAGE_POST_TOOL\x10\x05\x12\x12\n\x0eSTAGE_POST_RUN\x10\x06*[\n\x04Role\x12\x14\n\x10ROLE_UNSPECIFIED\x10\x00\x12\r\n\tROLE_USER\x10\x01\x12\x0e\n\nROLE_MODEL\x10\x02\x12\r\n\tROLE_TOOL\x10\x03\x12\x0f\n\x0bROLE_SYSTEM\x10\x04*b\n\x08\x44\x65\x63ision\x12\x18\n\x14\x44\x45\x43ISION_UNSPECIFIED\x10\x00\x12\x12\n\x0e\x44\x45\x43ISION_ALLOW\x10\x01\x12\x11\n\rDECISION_DENY\x10\x02\x12\x15\n\x11\x44\x45\x43ISION_ESCALATE\x10\x03\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -39,50 +39,50 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['_GUARDRAILCONTEXT_CHECKSENTRY']._serialized_options = b'8\001'
   _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._loaded_options = None
   _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._serialized_options = b'8\001'
-  _globals['_TRAJECTORYSTATUS']._serialized_start=2474
-  _globals['_TRAJECTORYSTATUS']._serialized_end=2685
-  _globals['_STAGE']._serialized_start=2688
-  _globals['_STAGE']._serialized_end=2841
-  _globals['_ROLE']._serialized_start=2843
-  _globals['_ROLE']._serialized_end=2934
-  _globals['_DECISION']._serialized_start=2936
-  _globals['_DECISION']._serialized_end=3034
+  _globals['_TRAJECTORYSTATUS']._serialized_start=2622
+  _globals['_TRAJECTORYSTATUS']._serialized_end=2833
+  _globals['_STAGE']._serialized_start=2836
+  _globals['_STAGE']._serialized_end=2989
+  _globals['_ROLE']._serialized_start=2991
+  _globals['_ROLE']._serialized_end=3082
+  _globals['_DECISION']._serialized_start=3084
+  _globals['_DECISION']._serialized_end=3182
   _globals['_SOURCECODE']._serialized_start=116
   _globals['_SOURCECODE']._serialized_end=160
   _globals['_PARAMETER']._serialized_start=162
   _globals['_PARAMETER']._serialized_end=222
   _globals['_TOOL']._serialized_start=225
-  _globals['_TOOL']._serialized_end=411
-  _globals['_AGENT']._serialized_start=414
-  _globals['_AGENT']._serialized_end=548
-  _globals['_PROMPT']._serialized_start=550
-  _globals['_PROMPT']._serialized_end=572
-  _globals['_TOOLREQUEST']._serialized_start=574
-  _globals['_TOOLREQUEST']._serialized_end=642
-  _globals['_TOOLRESPONSE']._serialized_start=644
-  _globals['_TOOLRESPONSE']._serialized_end=717
-  _globals['_CONTENT']._serialized_start=720
-  _globals['_CONTENT']._serialized_end=898
-  _globals['_TRAJECTORYSTEP']._serialized_start=901
-  _globals['_TRAJECTORYSTEP']._serialized_end=1084
-  _globals['_TRAJECTORY']._serialized_start=1087
-  _globals['_TRAJECTORY']._serialized_end=1590
-  _globals['_TRAJECTORY_METADATAENTRY']._serialized_start=1491
-  _globals['_TRAJECTORY_METADATAENTRY']._serialized_end=1562
-  _globals['_CHECK']._serialized_start=1592
-  _globals['_CHECK']._serialized_end=1664
-  _globals['_GUARDRAILCONTEXT']._serialized_start=1667
-  _globals['_GUARDRAILCONTEXT']._serialized_end=1819
-  _globals['_GUARDRAILCONTEXT_CHECKSENTRY']._serialized_start=1750
-  _globals['_GUARDRAILCONTEXT_CHECKSENTRY']._serialized_end=1819
-  _globals['_POLICYANNOTATIONS']._serialized_start=1822
-  _globals['_POLICYANNOTATIONS']._serialized_end=2018
-  _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._serialized_start=1950
-  _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._serialized_end=1995
-  _globals['_ADJUDICATION']._serialized_start=2021
-  _globals['_ADJUDICATION']._serialized_end=2173
-  _globals['_ADJUDICATEDSTEP']._serialized_start=2176
-  _globals['_ADJUDICATEDSTEP']._serialized_end=2348
-  _globals['_ADJUDICATEDTRAJECTORY']._serialized_start=2350
-  _globals['_ADJUDICATEDTRAJECTORY']._serialized_end=2471
+  _globals['_TOOL']._serialized_end=559
+  _globals['_AGENT']._serialized_start=562
+  _globals['_AGENT']._serialized_end=696
+  _globals['_PROMPT']._serialized_start=698
+  _globals['_PROMPT']._serialized_end=720
+  _globals['_TOOLREQUEST']._serialized_start=722
+  _globals['_TOOLREQUEST']._serialized_end=790
+  _globals['_TOOLRESPONSE']._serialized_start=792
+  _globals['_TOOLRESPONSE']._serialized_end=865
+  _globals['_CONTENT']._serialized_start=868
+  _globals['_CONTENT']._serialized_end=1046
+  _globals['_TRAJECTORYSTEP']._serialized_start=1049
+  _globals['_TRAJECTORYSTEP']._serialized_end=1232
+  _globals['_TRAJECTORY']._serialized_start=1235
+  _globals['_TRAJECTORY']._serialized_end=1738
+  _globals['_TRAJECTORY_METADATAENTRY']._serialized_start=1639
+  _globals['_TRAJECTORY_METADATAENTRY']._serialized_end=1710
+  _globals['_CHECK']._serialized_start=1740
+  _globals['_CHECK']._serialized_end=1812
+  _globals['_GUARDRAILCONTEXT']._serialized_start=1815
+  _globals['_GUARDRAILCONTEXT']._serialized_end=1967
+  _globals['_GUARDRAILCONTEXT_CHECKSENTRY']._serialized_start=1898
+  _globals['_GUARDRAILCONTEXT_CHECKSENTRY']._serialized_end=1967
+  _globals['_POLICYANNOTATIONS']._serialized_start=1970
+  _globals['_POLICYANNOTATIONS']._serialized_end=2166
+  _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._serialized_start=2098
+  _globals['_POLICYANNOTATIONS_CUSTOMENTRY']._serialized_end=2143
+  _globals['_ADJUDICATION']._serialized_start=2169
+  _globals['_ADJUDICATION']._serialized_end=2321
+  _globals['_ADJUDICATEDSTEP']._serialized_start=2324
+  _globals['_ADJUDICATEDSTEP']._serialized_end=2496
+  _globals['_ADJUDICATEDTRAJECTORY']._serialized_start=2498
+  _globals['_ADJUDICATEDTRAJECTORY']._serialized_end=2619
 # @@protoc_insertion_point(module_scope)

sondera/proto/sondera/core/v1/primitives_pb2.pyi

@@ -86,18 +86,24 @@ class Parameter(_message.Message):
     def __init__(self, name: _Optional[str] = ..., description: _Optional[str] = ..., type: _Optional[str] = ...) -> None: ...
 
 class Tool(_message.Message):
-    __slots__ = ("name", "description", "parameters", "response", "source")
+    __slots__ = ("id", "name", "description", "parameters", "parameters_json_schema", "response", "response_json_schema", "source")
+    ID_FIELD_NUMBER: _ClassVar[int]
     NAME_FIELD_NUMBER: _ClassVar[int]
     DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
     PARAMETERS_FIELD_NUMBER: _ClassVar[int]
+    PARAMETERS_JSON_SCHEMA_FIELD_NUMBER: _ClassVar[int]
     RESPONSE_FIELD_NUMBER: _ClassVar[int]
+    RESPONSE_JSON_SCHEMA_FIELD_NUMBER: _ClassVar[int]
     SOURCE_FIELD_NUMBER: _ClassVar[int]
+    id: str
     name: str
     description: str
     parameters: _containers.RepeatedCompositeFieldContainer[Parameter]
+    parameters_json_schema: str
     response: str
+    response_json_schema: str
     source: SourceCode
-    def __init__(self, name: _Optional[str] = ..., description: _Optional[str] = ..., parameters: _Optional[_Iterable[_Union[Parameter, _Mapping]]] = ..., response: _Optional[str] = ..., source: _Optional[_Union[SourceCode, _Mapping]] = ...) -> None: ...
+    def __init__(self, id: _Optional[str] = ..., name: _Optional[str] = ..., description: _Optional[str] = ..., parameters: _Optional[_Iterable[_Union[Parameter, _Mapping]]] = ..., parameters_json_schema: _Optional[str] = ..., response: _Optional[str] = ..., response_json_schema: _Optional[str] = ..., source: _Optional[_Union[SourceCode, _Mapping]] = ...) -> None: ...
 
 class Agent(_message.Message):
     __slots__ = ("id", "provider_id", "name", "description", "instruction", "tools")

sondera/types.py

@@ -213,6 +213,24 @@ class Decision(Enum):
     ESCALATE = "escalate"
 
 
+class Check(Model):
+    """Single guardrail check result."""
+
+    name: str
+    """Name of the guardrail check."""
+    flagged: bool
+    """Whether the check was flagged."""
+    message: str | None = None
+    """Optional message describing the check result."""
+
+
+class GuardrailContext(Model):
+    """Aggregated guardrail check results."""
+
+    checks: dict[str, Check] = Field(default_factory=dict)
+    """Map of check name to check result."""
+
+
 class PolicyAnnotation(Model):
     """Annotation from a policy evaluation."""
 
@@ -220,6 +238,10 @@ class PolicyAnnotation(Model):
     """Unique identifier of the policy that produced this annotation."""
     description: str
     """Human-readable description of why this annotation was added."""
+    escalate: bool = False
+    """Whether this policy requires escalation to a human or other oracle to decide the final verdict."""
+    escalate_arg: str = ""
+    """The argument passed to @escalate, if any."""
     custom: dict[str, str] = Field(default_factory=dict)
     """Custom key-value metadata from the policy."""
 
@@ -231,6 +253,8 @@ class Adjudication(Model):
     """Whether the input is allowed."""
     reason: str
     """Reason for the adjudication decision."""
+    policy_ids: list[str] = Field(default_factory=list)
+    """IDs of policies that contributed to this decision."""
     annotations: list[PolicyAnnotation] = Field(default_factory=list)
     """Annotations from policy evaluations."""
 
@@ -259,6 +283,8 @@ class AdjudicatedStep(Model):
     """Adjudication of the input."""
     step: TrajectoryStep
     """Step of the adjudication."""
+    guardrails: GuardrailContext | None = None
+    """Guardrail check results for this step."""
 
     @property
     def is_denied(self) -> bool:

sondera_harness-0.6.3.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: sondera-harness
+Version: 0.6.3
+Summary: Sondera Harness SDK for Python - Agent governance and policy enforcement
+Author-email: Sondera AI <sdk@sondera.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sondera-ai/harness-sdk-python
+Project-URL: Documentation, https://docs.sondera.ai
+Project-URL: Repository, https://github.com/sondera-ai/harness-sdk-python
+Project-URL: Issues, https://github.com/sondera-ai/harness-sdk-python/issues
+Project-URL: Changelog, https://github.com/sondera-ai/harness-sdk-python/blob/main/CHANGELOG.md
+Keywords: ai,agents,governance,policy,guardrails,llm,langchain,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cedar-python>=0.1.1
+Requires-Dist: click>=8.0.0
+Requires-Dist: click-default-group>=1.2.4
+Requires-Dist: grpcio>=1.76.0
+Requires-Dist: grpcio-tools>=1.76.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: textual>=6.11.0
+Provides-Extra: adk
+Requires-Dist: google-adk>=1.22.0; extra == "adk"
+Provides-Extra: langgraph
+Requires-Dist: langchain>=1.2.0; extra == "langgraph"
+Requires-Dist: langgraph>=1.0.5; extra == "langgraph"
+Provides-Extra: strands
+Requires-Dist: strands-agents>=1.21.0; extra == "strands"
+Provides-Extra: all
+Requires-Dist: google-adk>=1.22.0; extra == "all"
+Requires-Dist: langchain>=1.2.0; extra == "all"
+Requires-Dist: langgraph>=1.0.5; extra == "all"
+Requires-Dist: strands-agents>=1.21.0; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sondera-ai/harness-sdk-python/main/assets/sondera-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/sondera-ai/harness-sdk-python/main/assets/sondera-logo-light.svg">
+    <img alt="Sondera" src="https://raw.githubusercontent.com/sondera-ai/harness-sdk-python/main/assets/sondera-logo-light.svg" height="60">
+  </picture>
+
+  <h1>Sondera Harness</h1>
+
+  <p><strong>Deterministic guardrails for AI agents.</strong></p>
+
+  <p>Open-source. Works with LangGraph, ADK, Strands, or any custom agent.</p>
+
+  <p>
+    <a href="https://docs.sondera.ai/">Docs</a>
+    ·
+    <a href="https://docs.sondera.ai/quickstart/">Quickstart</a>
+    ·
+    <a href="https://github.com/sondera-ai/sondera-harness-python/tree/main/examples">Examples</a>
+    ·
+    <a href="https://discord.gg/8zMbcnDnZs">Discord</a>
+  </p>
+
+  <p>
+    <a href="https://pypi.org/project/sondera-harness/"><img src="https://img.shields.io/pypi/v/sondera-harness.svg" alt="PyPI version"></a>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/sondera-ai/sondera-harness-python.svg" alt="License: MIT"></a>
+  </p>
+
+</div>
+
+---
+
+## What is Sondera Harness?
+
+Sondera Harness evaluates [Cedar](https://www.cedarpolicy.com/) policies before your agent's actions execute. When a policy denies an action, the agent gets a reason why and can try a different approach. Same input, same verdict. Deterministic, not probabilistic.
+
+**Example policy:**
+
+```cedar
+forbid(principal, action, resource)
+when { context has parameters_json && context.parameters_json like "*rm -rf*" };
+```
+
+This policy stops your agent from running `rm -rf`, every time.
+
+## Quickstart
+
+### 1. Install
+
+```bash
+uv add "sondera-harness[langgraph]"   # or: pip install "sondera-harness[langgraph]"
+```
+
+### 2. Add to Your Agent (LangGraph)
+
+```python
+from langchain.agents import create_agent
+from sondera.harness import SonderaRemoteHarness
+from sondera.langgraph import SonderaHarnessMiddleware, Strategy, create_agent_from_langchain_tools
+
+# Analyze your tools and create agent metadata
+sondera_agent = create_agent_from_langchain_tools(
+    tools=my_tools,
+    agent_id="langchain-agent",
+    agent_name="My LangChain Agent",
+    agent_description="An agent that helps with tasks",
+)
+
+# Create harness with agent
+harness = SonderaRemoteHarness(agent=sondera_agent)
+
+# Create middleware
+middleware = SonderaHarnessMiddleware(
+    harness=harness,
+    strategy=Strategy.BLOCK,  # or Strategy.STEER
+)
+
+# Create agent with middleware
+agent = create_agent(
+    model=my_model,
+    tools=my_tools,
+    middleware=[middleware],
+)
+```
+
+Also supports [Google ADK](https://docs.sondera.ai/integrations/adk/), [Strands](https://docs.sondera.ai/integrations/strands/), and [custom integrations](https://docs.sondera.ai/integrations/custom/).
+
+> [!NOTE]
+> This example uses Sondera Platform ([free account](https://sondera.ai)), which also enables the TUI below. For local-only development, see [CedarPolicyHarness](https://docs.sondera.ai/integrations/custom/).
+
+### 3. See It in Action
+
+<div align="center">
+  <img src="docs/src/assets/sondera-tui.gif" alt="Sondera TUI" width="700" />
+</div>
+
+```bash
+uv run sondera   # or: sondera (if installed via pip)
+```
+
+## Why Sondera Harness?
+
+- **Steer, don't block:** Denied actions include a reason. Return it to the model, and it tries something else.
+- **Deterministic:** Stop debugging prompts. Rules are predictable.
+- **Drop-in integration:** Native middleware for LangGraph, Google ADK, and Strands.
+- **Full observability:** Every action, every decision, every reason. Audit-ready.
+
+## Documentation
+
+- [Quickstart](https://docs.sondera.ai/quickstart/)
+- [Writing Policies](https://docs.sondera.ai/writing-policies/)
+- [Integrations](https://docs.sondera.ai/integrations/)
+- [Reference](https://docs.sondera.ai/reference/)
+
+## Community
+
+- [Discord](https://discord.gg/8zMbcnDnZs) for questions and feedback
+- [GitHub Issues](https://github.com/sondera-ai/sondera-harness-python/issues) for bugs
+- [Contributing](CONTRIBUTING.md) for development setup
+
+## License
+
+[MIT](LICENSE)

{sondera_harness-0.6.1.dist-info → sondera_harness-0.6.3.dist-info}/RECORD

@@ -1,21 +1,21 @@
-sondera/__init__.py,sha256=g6Ewr03q_2JZGIJ9APVs-6MLvZsAEtQJ2dcYEp4a6oc,2695
+sondera/__init__.py,sha256=0Z1R6ZkA5VSE_3ZCCgfeecm5nU6mFBdl4-18b8Nwt3Y,3558
 sondera/__main__.py,sha256=MNgWvrV4g4Ot653Ngi2D4cAOyRIG19qHAWLzQecsMdg,66
 sondera/cli.py,sha256=owchF-eA6kttYGTSsLl0B7XJMmn9O2n2LFjpfYQvznQ,494
 sondera/exceptions.py,sha256=vtuToFc5tSlzAyVYvayyOatKBcoenisDA1RN2yk9aSI,3584
 sondera/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sondera/settings.py,sha256=bLB98vT75aXKh5ihYnCd0dTk1AdfUUaGuPkyzhcldE0,459
-sondera/types.py,sha256=T6_vZQwXO4CtOW1B9X9JhuSuN7FvE6qq4T_Li1KLZbc,9556
+sondera/types.py,sha256=t4TbVcieoPgGr9wje0jz0eFmXPmfOvdqsKds8aKgMDI,10428
 sondera/adk/__init__.py,sha256=weoilnJyr8JNBv2HK6s3hhW-6rOBGBcNwwkKk1oHVFE,77
 sondera/adk/analyze.py,sha256=IurwCWPZlNbMkIwi3TGWUu4k-w_VmKCkAnVFbfipbxY,7974
-sondera/adk/plugin.py,sha256=HfVdbzp0bHc4YIs0MjNO-pwrMMex1AsKbQWoQNp7dmI,13047
+sondera/adk/plugin.py,sha256=ioxJCRaAC5Rt73h_Y6G3LgHSkz28K1hVi8nZGyCdAgc,13047
 sondera/harness/__init__.py,sha256=gK0rFEyixD9X67pFyWKQpcq_oZ6pep6up8K0Y-zvXUc,221
 sondera/harness/abc.py,sha256=hL77Rlzy1B-DjFexhskGm_9j5Sue-TaWdlSnjr-Al70,3548
 sondera/harness/cedar/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sondera/harness/cedar/harness.py,sha256=mkskBjz4REVhV79r_zgrRBQjwGqbKom7NlpJr8aM0P8,12128
+sondera/harness/cedar/harness.py,sha256=ZTUa1TuzNBLESkLMZZu_jAVOnqMOYLGgD1RbylqbhMk,15597
 sondera/harness/cedar/schema.py,sha256=jDAGdLciK3fQ-7yKrqeFkU4YHQg-KwWvTi1leEuYVxo,7766
 sondera/harness/sondera/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sondera/harness/sondera/_grpc.py,sha256=wAhk5H3BZvyi72RtUo1nuJFqp-U4UXe44l2eODDJrF8,12504
-sondera/harness/sondera/harness.py,sha256=ueR2Khfmz3R4-fZrQsv_AtjOC7OAN861UEX0D-Okmwg,31710
+sondera/harness/sondera/_grpc.py,sha256=vLVJwJBtDwX-p8qZPfShpChKxdP3lSFoTV6QiL4dh7s,14708
+sondera/harness/sondera/harness.py,sha256=Xg0zc6DZbYvAVceJMlC8fL6D-qX8J-xI1OqPHb-Taxk,31231
 sondera/langgraph/__init__.py,sha256=F2eNoPp944tvGbf9a4etNh3-o49WOPrcs9EFVT0OYYw,473
 sondera/langgraph/analyze.py,sha256=1n-1yKr7-kfdFNSBe9JozZ08oJeYvPqKkFttcQ4MXHI,20514
 sondera/langgraph/exceptions.py,sha256=BRdh1gpELb3_WZ9Bh_UUwZsIOcIPrpQCD-7LnnAGeV4,501
@@ -42,8 +42,8 @@ sondera/proto/google/protobuf/wrappers_pb2_grpc.py,sha256=SO9GezWgSOXwclY-Jjo8lv
 sondera/proto/sondera/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sondera/proto/sondera/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sondera/proto/sondera/core/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sondera/proto/sondera/core/v1/primitives_pb2.py,sha256=12rqeMQnq7OOVIaQBE3ig7hiMUtOK-ENCuiz-T91nMo,9231
-sondera/proto/sondera/core/v1/primitives_pb2.pyi,sha256=IFzGfoUe2TcQqZJRT-jmyofosmOOmrtWoTRPIqqLa5E,11824
+sondera/proto/sondera/core/v1/primitives_pb2.py,sha256=q5BvZY4QIySmfUc5tGl2AiwAtYaZCbQgXcOuf3BaUfs,9492
+sondera/proto/sondera/core/v1/primitives_pb2.pyi,sha256=yRiHab6ut8MzJDZHas2kXvvJUjbXwAjkQ75rpkmZHs4,12216
 sondera/proto/sondera/core/v1/primitives_pb2_grpc.py,sha256=YNObfhmUBQVh_n-kRidSAi_V4sPLf2Mo9Jc7hEEHT2s,906
 sondera/proto/sondera/harness/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sondera/proto/sondera/harness/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -70,9 +70,9 @@ sondera/tui/widgets/tool_card.py,sha256=3yNQcc_umcan4V1S5GiEKd7l4YA_atibwn3HF0n6
 sondera/tui/widgets/violation_panel.py,sha256=fowe4KWb13NXLX0_RAxEPdRqYeyGzlImpRs4_L9y1zI,2933
 sondera/tui/widgets/violations_list.py,sha256=86qICAsQOC6kjQLs64WxK7u59vEJ8kvfiToLVlzFyHM,2866
 sondera/tui/widgets/violations_summary.py,sha256=e2LwqlB1aS8sZ2gEC5clk7siA16NSgePU1mpv8T1iTc,4473
-sondera_harness-0.6.1.dist-info/licenses/LICENSE,sha256=DmSfauhgrslTxZOcDAmcYqsqsKBkMqVh3PYdjPghNbU,1070
-sondera_harness-0.6.1.dist-info/METADATA,sha256=ZNFNrXzrWJEHRFmLfAqqmRYwxgxP-4oheQRKjpcT_EQ,8899
-sondera_harness-0.6.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-sondera_harness-0.6.1.dist-info/entry_points.txt,sha256=e9aHpIPUUlP5MPKORk7k6ekUfZLN3RyO1MEJa-nCzK4,44
-sondera_harness-0.6.1.dist-info/top_level.txt,sha256=BR0X8Gq9CCpwbQg5evpQfy5zwp9fTuGnlJhXSNqQ_hA,8
-sondera_harness-0.6.1.dist-info/RECORD,,
+sondera_harness-0.6.3.dist-info/licenses/LICENSE,sha256=DmSfauhgrslTxZOcDAmcYqsqsKBkMqVh3PYdjPghNbU,1070
+sondera_harness-0.6.3.dist-info/METADATA,sha256=cWb8iOVxQLKyIRcNq8902znCu6oqPr8IRhU6Yvm64lg,6419
+sondera_harness-0.6.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+sondera_harness-0.6.3.dist-info/entry_points.txt,sha256=5cLgW0-GzEwNnQjXIhGT21iFprQb1lftBaFJjC4IrgE,78
+sondera_harness-0.6.3.dist-info/top_level.txt,sha256=BR0X8Gq9CCpwbQg5evpQfy5zwp9fTuGnlJhXSNqQ_hA,8
+sondera_harness-0.6.3.dist-info/RECORD,,

{sondera_harness-0.6.1.dist-info → sondera_harness-0.6.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{sondera_harness-0.6.1.dist-info → sondera_harness-0.6.3.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 sondera = sondera.cli:cli
+sondera-harness = sondera.cli:cli

sondera_harness-0.6.1.dist-info/METADATA

@@ -1,323 +0,0 @@
-Metadata-Version: 2.4
-Name: sondera-harness
-Version: 0.6.1
-Summary: Sondera Harness SDK for Python - Agent governance and policy enforcement
-Author-email: Sondera AI <sdk@sondera.ai>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/sondera-ai/harness-sdk-python
-Project-URL: Documentation, https://docs.sondera.ai
-Project-URL: Repository, https://github.com/sondera-ai/harness-sdk-python
-Project-URL: Issues, https://github.com/sondera-ai/harness-sdk-python/issues
-Project-URL: Changelog, https://github.com/sondera-ai/harness-sdk-python/blob/main/CHANGELOG.md
-Keywords: ai,agents,governance,policy,guardrails,llm,langchain,langgraph
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Security
-Classifier: Typing :: Typed
-Requires-Python: <3.15,>=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: cedar-python>=0.1.1
-Requires-Dist: click>=8.0.0
-Requires-Dist: click-default-group>=1.2.4
-Requires-Dist: grpcio>=1.76.0
-Requires-Dist: grpcio-tools>=1.76.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.12.0
-Requires-Dist: pydantic-settings>=2.12.0
-Requires-Dist: textual>=6.11.0
-Provides-Extra: adk
-Requires-Dist: google-adk>=1.22.0; extra == "adk"
-Provides-Extra: langgraph
-Requires-Dist: langchain>=1.2.0; extra == "langgraph"
-Requires-Dist: langgraph>=1.0.5; extra == "langgraph"
-Provides-Extra: strands
-Requires-Dist: strands-agents>=1.21.0; extra == "strands"
-Provides-Extra: all
-Requires-Dist: google-adk>=1.22.0; extra == "all"
-Requires-Dist: langchain>=1.2.0; extra == "all"
-Requires-Dist: langgraph>=1.0.5; extra == "all"
-Requires-Dist: strands-agents>=1.21.0; extra == "all"
-Dynamic: license-file
-
-# Sondera Harness SDK for Python
-
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
->
-> One step at a time. One action at a time. One trajectory at a time.
-> 
-
-AI agents systems operate beyond traditional security boundaries, making autonomous decisions, calling tools, and accessing resources based on context that changes with every execution. Sondera SDK provides runtime governance for these agentic systems, answering not just "can this agent do X?" but "should it do X here, now, with this data?" Built for developers deploying agents through LangGraph, Google ADK, and Strands, Sondera enables real-time trajectory tracking, policy-as-code enforcement via Cedar, and behavioral adjudication so you can ship agents with confidence.
-
-## Features
-
-- **Managed harness-as-a-service** with the Sondera Harness for enterprise policy governance and guardrails
-- **Local policy-as-code** using Cedar policy language in the Cedar Policy Harness
-- **Real-time trajectory** observability, adjudication, and steering
-- **Scaffold integrations** for LangGraph, Google ADK, and Strands
-- **CLI and TUI** for monitoring agent behavior
-
-## Installation
-
-```bash
-uv add sondera-harness
-```
-
-### Optional Dependencies
-
-Install extras for specific framework integrations:
-
-```bash
-# Google ADK support
-uv add sondera-harness --extra adk
-
-# LangGraph support
-uv add sondera-harness --extra langgraph
-
-# Strands support
-uv add sondera-harness --extra strands
-
-# All integrations
-uv add sondera-harness --all-extras
-```
-
-## Quick Start
-
-### Configuration
-
-Set your API credentials via environment variables:
-
-```bash
-export SONDERA_HARNESS_ENDPOINT="your-harness.sondera.ai:443"
-export SONDERA_API_TOKEN="<YOUR_SONDERA_API_KEY>"
-```
-
-Or create a `.env` file or `~/.sondera/env`:
-
-```env
-SONDERA_HARNESS_ENDPOINT=your-harness.sondera.ai:443
-SONDERA_API_TOKEN=<YOUR_SONDERA_API_KEY>
-```
-
-## Scaffold Integrations
-
-### LangGraph / LangChain
-
-```python
-from langchain.agents import create_agent
-from sondera.harness import SonderaRemoteHarness
-from sondera.langgraph import SonderaHarnessMiddleware, Strategy, create_agent_from_langchain_tools
-
-# Analyze your tools and create agent metadata
-sondera_agent = create_agent_from_langchain_tools(
-    tools=my_tools,
-    agent_id="langchain-agent",
-    agent_name="My LangChain Agent",
-    agent_description="An agent that helps with tasks",
-)
-
-# Create harness with agent
-harness = SonderaRemoteHarness(agent=sondera_agent)
-
-# Create middleware
-middleware = SonderaHarnessMiddleware(
-    harness=harness,
-    strategy=Strategy.BLOCK,  # or Strategy.STEER
-)
-
-# Create agent with middleware
-agent = create_agent(
-    model=my_model,
-    tools=my_tools,
-    middleware=[middleware],
-)
-```
-
-### Google ADK
-
-```python
-from google.adk.agents import Agent
-from google.adk.runners import Runner
-from sondera.harness import SonderaRemoteHarness
-from sondera.adk import SonderaHarnessPlugin
-
-# Create harness
-harness = SonderaRemoteHarness(
-    sondera_api_key="<YOUR_SONDERA_API_KEY>",
-)
-
-# Create plugin
-plugin = SonderaHarnessPlugin(harness=harness)
-
-# Create agent
-agent = Agent(
-    name="my-adk-agent",
-    model="gemini-2.0-flash",
-    instruction="Be helpful and safe",
-    tools=[...],
-)
-
-# Create runner with plugin
-runner = Runner(
-    agent=agent,
-    app_name="my-app",
-    plugins=[plugin],
-)
-```
-
-### Strands Agents
-
-```python
-from strands import Agent
-from sondera.harness import SonderaRemoteHarness
-from sondera.strands import SonderaHarnessHook
-
-# Create harness
-harness = SonderaRemoteHarness(
-    sondera_api_key="<YOUR_SONDERA_API_KEY>",
-)
-
-# Create hook
-hook = SonderaHarnessHook(harness=harness)
-
-# Create agent with hook
-agent = Agent(
-    system_prompt="You are a helpful assistant",
-    model="anthropic.claude-3-5-sonnet-20241022-v2:0",
-    hooks=[hook],
-)
-
-# Run agent (hooks fire automatically)
-response = agent("What is 5 + 3?")
-```
-
-### Custom Scaffold 
-
-```python
-from sondera import SonderaRemoteHarness, Agent, PromptContent, Role, Stage
-
-# Create a harness instance
-harness = SonderaRemoteHarness(
-    sondera_harness_endpoint="localhost:50051",
-    sondera_api_key="<YOUR_SONDERA_API_KEY>",
-    sondera_harness_client_secure=True,  # Enable TLS for production
-)
-
-# Define your agent
-agent = Agent(
-    id="my-agent",
-    provider_id="custom",
-    name="My Assistant",
-    description="A helpful AI assistant",
-    instruction="Be helpful, accurate, and safe",
-    tools=[],
-)
-
-# Initialize a trajectory
-await harness.initialize(agent=agent)
-
-# Adjudicate user input
-adjudication = await harness.adjudicate(
-    Stage.PRE_MODEL,
-    Role.USER,
-    PromptContent(text="Hello, can you help me?"),
-)
-
-if adjudication.is_allowed:
-    # Proceed with agent logic
-    pass
-elif adjudication.is_denied:
-    print(f"Request blocked: {adjudication.reason}")
-
-# Finalize the trajectory
-await harness.finalize()
-```
-
-## Remote and Local Harnesses
-
-### Cedar Policy Harness (Local Only)
-
-For a local harness deployment, you can use the `CedarPolicyHarness` to evaluate Cedar policies:
-
-```python
-from sondera.harness import CedarPolicyHarness
-from sondera import Agent
-
-# Define Cedar policies
-policies = '''
-@id("forbid-dangerous-bash")
-forbid(
-  principal,
-  action == Coding_Agent::Action::"Bash",
-  resource
-)
-when {
-  context has parameters &&
-  (context.parameters.command like "*rm -rf /*" ||
-   context.parameters.command like "*mkfs*" ||
-   context.parameters.command like "*dd if=/dev/zero*" ||
-   context.parameters.command like "*> /dev/sda*")
-};
-'''
-
-# Create local policy engine
-harness = CedarPolicyHarness(
-    policy_set=policies,
-    agent=my_agent,
-)
-
-await harness.initialize()
-# Use same adjudication API as RemoteHarness
-```
-
-## CLI & TUI
-
-Launch the Sondera TUI for monitoring (note, requires a Sondera account and API key):
-
-```bash
-sondera
-```
-
-The TUI provides:
-- Real-time agent and trajectory overview
-- Adjudication history and policy violations
-- Agent details and tool inspection
-
-## Examples
-
-See the [examples/](examples/) directory for complete demos:
-
-- **LangGraph**: Investment chatbot with policy enforcement
-- **ADK**: Payment and healthcare agents
-- **Strands**: Various agent implementations
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SONDERA_HARNESS_ENDPOINT` | Harness service endpoint | `localhost:50051` |
-| `SONDERA_API_TOKEN` | JWT authentication token | Required for remote |
-
-## Requirements
-
-- Python 3.12 or higher (up to 3.14)
-
-## Security
-
-See [SECURITY.md](SECURITY.md) for security best practices and vulnerability reporting.
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
-
-## License
-
-MIT - see [LICENSE](LICENSE) for details.