tidy

Author: calvingiles

src/google/adk/approval/__init__.py

@@ -12,6 +12,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# from .approval_handler import ApprovalHandler
-# from .approval_tool import ApprovalConfig
-# from .approval_processor import request_processor
+"""Provides foundational classes and handlers for managing approvals in the ADK."""
+

src/google/adk/approval/approval_grant.py

@@ -1,3 +1,12 @@
+
+"""Defines the core data structures for representing approval grants.
+
+This module includes classes for:
+- `ApprovalActor`: Represents an entity (user, agent, tool) involved in an approval.
+- `ApprovalEffect`: Enumerates the possible outcomes of an approval (allow, deny, challenge).
+- `ApprovalGrant`: Encapsulates the details of a permission grant, including the
+  effect, actions, resources, grantee, grantor, and optional expiration.
+"""
 from __future__ import annotations
 from datetime import datetime
 from enum import Enum
@@ -8,35 +17,43 @@
 
 class ApprovalActor(BaseModel):
   id: str
+  """A unique identifier for the actor (e.g., user ID, agent session ID, tool call ID)."""
   type: str = Literal["user", "agent", "tool"]
+  """The type of the actor."""
   on_behalf_of: ApprovalActor | None = None
+  """The actor on whose behalf this actor is operating, if any (e.g., an agent acting on behalf of a user)."""
 
 
 class ApprovalEffect(str, Enum):
   allow = "allow"
+  """Indicates that the requested action is permitted."""
   deny = "deny"
+  """Indicates that the requested action is explicitly forbidden."""
   challenge = "challenge"
+  """Indicates that further information or confirmation is required before allowing or denying."""
 
 
 ApprovalAction = str
+"""Type alias for an action string (e.g., 'tool:read_file', 'agent:use')."""
 ApprovalResource = str
+"""Type alias for a resource string (e.g., 'tool:files:/path/to/file', 'agent:agent_name')."""
 
 
 class ApprovalGrant(BaseModel):
   """Effect the actions on the resources to the grantee by the grantor until the expiration."""
 
   effect: Literal[ApprovalEffect.allow, ApprovalEffect.deny]
-  """Whether to grant an allow or deny."""
+  """The effect of this grant, either allowing or denying the specified actions on the resources."""
   actions: list[ApprovalAction]
-  """The actions to which the grant will effect."""
+  """A list of actions (e.g., 'tool:read_file') that this grant permits or denies."""
   resources: list[ApprovalResource]
-  """The resources that this grant affects."""
+  """A list of resources (e.g., 'tool:files:/path/to/data.txt') to which this grant applies."""
   grantee: ApprovalActor
-  """Who the grant applies to."""
+  """The actor (user, agent, or tool) to whom the permissions are granted."""
   grantor: ApprovalActor
-  """The permission holder that granted toe access (e.g. user, or delegated by a parent agent)."""
-  expiration_time: Optional[datetime] = None  # Optional expiration time
-  """The time after which the grant ceases to be valid."""
+  """The actor who authorized this grant (e.g., an end-user or a delegating agent)."""
+  expiration_time: Optional[datetime] = None
+  """The optional time after which this grant is no longer valid. If None, the grant does not expire."""
 
   comment: Optional[str] = None
-  """Comment from the grantor (typically the end user) from the point of granting. This is used when communicating a grant update to a model, for example a deny, to explain the reason."""
+  """An optional comment from the grantor, often used to explain the reason for a denial or to provide context for an approval."""

src/google/adk/approval/approval_handler.py

@@ -12,7 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Approval handler for managing tool approvals."""
+"""Handles the logic for managing and evaluating approval requests against policies and grants.
+
+This module provides the `ApprovalHandler` class, which is responsible for:
+- Parsing and storing approval responses.
+- Determining if a given function call requires approval based on registered policies and existing grants.
+- Generating approval requests (challenges) when necessary.
+- Checking if actions on resources are permitted by existing grants.
+"""
 
 from __future__ import annotations
 
@@ -33,14 +40,31 @@
 
 
 class ApprovalHandler(object):
-  """Handles approval requests and responses."""
+  """Manages the lifecycle of approval requests, from checking policies to storing grants.
+
+  This class provides static methods to interact with the approval system. It does not
+  maintain its own state but operates on the state provided to its methods (typically
+  session state).
+  """
 
   @classmethod
   def parse_and_store_approval_responses(
       cls,
       initial_grants: list[ApprovalGrant],
       approval_responses: list[ApprovalResponse],
   ) -> list[ApprovalGrant]:
+    """Parses approval responses and extracts new grants.
+
+    Compares grants from approval responses with existing initial grants to identify
+    and return only the newly added grants.
+
+    Args:
+        initial_grants: A list of already existing approval grants.
+        approval_responses: A list of approval responses, each potentially containing grants.
+
+    Returns:
+        A list of new `ApprovalGrant` objects that were not present in `initial_grants`.
+    """
     extra_grants = []
     for approval_response in approval_responses:
       added_grants = [
@@ -61,6 +85,33 @@ def get_approval_request(
       user_id: str,
       session_id: str,
   ) -> Optional[Dict[str, Any]]:
+    """Determines if a function call requires approval and generates a request if so.
+
+    This method checks the given `function_call` against registered approval policies
+    and existing grants in the `state`. If approval is required (i.e., there are
+    pending challenges), it updates the `tool_context` to suspend the function call
+    and request approval.
+
+    If the function call is already approved or doesn't require approval, it updates
+    the `tool_context` to mark the function call as resumed.
+
+    If a deny grant explicitly forbids the call, an `ApprovalDenied` exception is caught,
+    and the function call is marked as cancelled.
+
+    Args:
+        function_call: The `FunctionCall` object to be checked.
+        state: The current session state, containing existing grants and suspended calls.
+        tool_context: The context for the current tool call, used to update its status
+                      and request approval.
+        user_id: The ID of the user initiating the call.
+        session_id: The ID of the current session.
+
+    Returns:
+        A dictionary with a "status" key if approval is requested or denied:
+        - {"status": "approval_requested"} if challenges are pending.
+        - {"status": "denied", "denied_challenges": ...} if the call is denied.
+        Returns `None` if the function call can proceed without further approval.
+    """
     try:
       if approval_request := cls._get_pending_challenges(
           state=state,
@@ -115,16 +166,30 @@ def _get_pending_challenges(
       user_id: str,
       session_id: str,
   ) -> Optional[ApprovalRequest]:
-    """Check if an approval exists for the given tool call.
+    """Checks a tool call against policies and grants to identify pending challenges.
+
+    This method evaluates the `tool_call` against all registered `ApprovalPolicy`
+    objects relevant to the tool. It then checks existing `ApprovalGrant` objects
+    in the `state` to see if the required actions on resources are permitted.
+
+    If any required action/resource pair is explicitly denied by a grant, this method
+    raises an `ApprovalDenied` exception.
+
+    If there are action/resource pairs required by policies that are not covered by
+    any existing allow grants, these are collected into an `ApprovalRequest`.
 
     Args:
-        state: The session state.
-        tool_name: The name of the tool.
-        tool_args: The arguments being passed to the tool.
-        function_call_id: The ID of the function call.
+        state: The session state or a dictionary containing at least `approvals__grants`.
+        tool_call: The `FunctionCall` to be evaluated.
+        user_id: The ID of the user initiating the call.
+        session_id: The ID of the current session.
+
+    Returns:
+        An `ApprovalRequest` object if there are unmet challenges, otherwise `None`.
 
     Raises:
-      ApprovalDenied: if the an approval with effect Deny matches.
+        ApprovalDenied: If an existing grant explicitly denies one of the required
+                        action/resource pairs.
     """
 
     policies = ApprovalPolicyRegistry.get_tool_policies(tool_call.name)
@@ -195,24 +260,40 @@ def _get_pending_challenges(
 
   @classmethod
   def _get_existing_grants(cls, state: State) -> list[ApprovalGrant]:
+    """Retrieves and validates existing approval grants from the state.
+
+    Args:
+        state: The session state, expected to contain an `approvals__grants` key
+               with a list of grant dictionaries.
+
+    Returns:
+        A list of `ApprovalGrant` objects.
+    """
     return [
         ApprovalGrant.model_validate(grant)
         for grant in state.get("approvals__grants", [])
     ]
 
   @staticmethod
-  def _resource_met(policy_resource, grant_resource):
-    """Check if a policy resource matches a grant resource.
+  def _resource_met(policy_resource: str, grant_resource: str) -> bool:
+    """Checks if a policy resource string matches a grant resource string, supporting wildcards.
+
+    The `grant_resource` can contain wildcards (`*`) which match any sequence of characters
+    within a segment, or an entire segment if the segment itself is `*`.
+    Resource strings are colon-separated (e.g., "namespace:type:identifier").
 
-    Grant resources can contain wildcards (*) which match any value
-    in that position.
+    Examples:
+      - `_resource_met("tool:files:read", "tool:files:*")` -> `True`
+      - `_resource_met("tool:files:read", "tool:*:read")` -> `True`
+      - `_resource_met("tool:files:read", "*")` -> `True`
+      - `_resource_met("foo:bar", "foo:baz")` -> `False`
 
     Args:
-        policy_resource: The resource being accessed
-        grant_resource: The resource in the grant, may contain wildcards
+        policy_resource: The specific resource being accessed (e.g., "tool:files:/data/my_file.txt").
+        grant_resource: The resource pattern from a grant (e.g., "tool:files:*", "*").
 
     Returns:
-        bool: True if the policy resource matches the grant resource pattern
+        `True` if the `policy_resource` matches the `grant_resource` pattern, `False` otherwise.
     """
     # Full wildcard matches anything
     if grant_resource == "*":
@@ -245,7 +326,20 @@ def _resource_met(policy_resource, grant_resource):
     return True
 
   @classmethod
-  def _check_actor(cls, actor, grantee) -> bool:
+  def _check_actor(cls, actor: ApprovalActor, grantee: ApprovalActor) -> bool:
+    """Recursively checks if an `actor` matches a `grantee` definition, including `on_behalf_of`.
+
+    This method verifies that the `id` and `type` of the `actor` match the `grantee`.
+    If `grantee.on_behalf_of` is set, it recursively checks that `actor.on_behalf_of`
+    also matches.
+
+    Args:
+        actor: The `ApprovalActor` requesting access.
+        grantee: The `ApprovalActor` specified in a grant.
+
+    Returns:
+        `True` if the actor matches the grantee definition, `False` otherwise.
+    """
     # Check if the grantee IDs match
     if not cls._check_actor_id(actor_id=actor.id, grantee_id=grantee.id):
       return False
@@ -264,7 +358,19 @@ def _check_actor(cls, actor, grantee) -> bool:
     return True
 
   @classmethod
-  def _check_actor_id(cls, actor_id, grantee_id) -> bool:
+  def _check_actor_id(cls, actor_id: str, grantee_id: str) -> bool:
+    """Checks if an actor ID matches a grantee ID, supporting wildcards.
+
+    Similar to `_resource_met`, but for actor IDs. The `grantee_id` can contain
+    wildcards (`*`) to match parts of or the entire `actor_id`.
+
+    Args:
+        actor_id: The ID of the actor requesting access.
+        grantee_id: The ID pattern from a grant.
+
+    Returns:
+        `True` if the `actor_id` matches the `grantee_id` pattern, `False` otherwise.
+    """
     if actor_id == grantee_id:
       return True
 
@@ -306,16 +412,24 @@ def _action_granted_for_resource(
       policy_resource: str,
       actor: ApprovalActor,
   ) -> Optional[Literal[ApprovalEffect.allow, ApprovalEffect.deny]]:
-    """Check if the given action on the resource is granted by this grant.
+    """Checks if a specific action on a resource by an actor is permitted or denied by a single grant.
+
+    This method verifies:
+    1. The `policy_action` is listed in `grant.actions`.
+    2. The `actor` matches `grant.grantee` (using `_check_actor`).
+    3. The `policy_resource` matches one of the `grant.resources` (using `_resource_met`).
+
+    If all conditions are met, it returns the `grant.effect` (allow or deny).
 
     Args:
-        grant: The approval grant to check against
-        policy_action: The action being requested
-        policy_resource: The resource being accessed
-        actor: The actor requesting the action
+        grant: The `ApprovalGrant` to check against.
+        policy_action: The action being attempted (e.g., "tool:files:read").
+        policy_resource: The resource being accessed (e.g., "tool:files:/data/my_doc.txt").
+        actor: The `ApprovalActor` attempting the action.
 
     Returns:
-        The effect (allow/deny) if granted, None if not applicable
+        `ApprovalEffect.allow` or `ApprovalEffect.deny` if the grant applies and matches,
+        otherwise `None`.
     """
     # Check if the action is in the grant's actions
     if policy_action not in grant.actions:
@@ -340,16 +454,25 @@ def _check_action_on_resource_against_grants(
       grants: list[ApprovalGrant],
       actor: ApprovalActor,
   ) -> Optional[Literal[ApprovalEffect.allow, ApprovalEffect.deny]]:
-    """Check if the given action on the resource is granted by any of the grants.
+    """Evaluates an action on a resource against a list of grants to determine its effective status.
+
+    Deny grants are prioritized. If any deny grant matches the action, resource, and actor,
+    `ApprovalEffect.deny` is returned immediately.
+    If no deny grants match, allow grants are checked. If an allow grant matches,
+    `ApprovalEffect.allow` is returned.
+    If no grants match, `None` is returned, indicating the action is not explicitly
+    allowed or denied by the provided grants.
 
     Args:
-        action: The action being requested
-        resource: The resource being accessed
-        grants: The list of grants to check against
-        actor: The actor requesting the action
+        action: The `ApprovalAction` being attempted.
+        resource: The resource string being accessed.
+        grants: A list of `ApprovalGrant` objects to check against.
+        actor: The `ApprovalActor` attempting the action.
 
     Returns:
-        The effect (allow/deny) if granted, None if not applicable
+        `ApprovalEffect.allow` if an allow grant matches and no deny grant matches.
+        `ApprovalEffect.deny` if a deny grant matches.
+        `None` if no grants explicitly cover the action/resource/actor combination.
     """
     # Prioritize deny grants, then check allow grants
     allow_grants = [