docs: add comprehensive Google-style docstrings to unified_pdp

Add complete Args, Returns, Raises, and Attributes documentation to all
public functions and methods in the unified_pdp plugin, matching the
project's docstring style with full parameter descriptions.

Files updated:
- adapter.py: PolicyEvaluationError, PolicyEngineAdapter methods
- cache.py: _build_cache_key, _CacheEntry, DecisionCache methods
- pdp.py: PolicyDecisionPoint and all evaluation/combination methods
- engines/cedar_engine.py: CedarEngineAdapter and all methods
- engines/mac_engine.py: MACEngineAdapter and all methods
- engines/native_engine.py: NativeRBACAdapter and all methods
- engines/opa_engine.py: OPAEngineAdapter and all methods
- unified_pdp.py: shutdown lifecycle method

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

Author: crivetimihai

plugins/unified_pdp/adapter.py

@@ -32,7 +32,17 @@
 
 
 class PolicyEvaluationError(Exception):
-    """Raised when an engine fails to evaluate a request (network, timeout, …)."""
+    """Raised when an engine fails to evaluate a request (network, timeout, etc.).
+
+    Args:
+        engine: The engine type that raised the error.
+        message: Human-readable error description.
+        cause: Optional underlying exception that caused this error.
+
+    Attributes:
+        engine: The engine type that raised the error.
+        cause: The underlying exception, if any.
+    """
 
     def __init__(self, engine: EngineType, message: str, cause: Exception | None = None):
         self.engine = engine
@@ -67,7 +77,11 @@ class PolicyEngineAdapter(ABC):
     @property
     @abstractmethod
     def engine_type(self) -> EngineType:
-        """Which engine this adapter represents."""
+        """Return the engine type identifier for this adapter.
+
+        Returns:
+            EngineType enum value identifying which policy engine this adapter wraps.
+        """
 
     # ------------------------------------------------------------------
     # Core evaluation
@@ -81,18 +95,20 @@ async def evaluate(
         resource: Resource,
         context: Context,
     ) -> EngineDecision:
-        """Evaluate a single access request.
-
-        Returns
-        -------
-        EngineDecision
-            The engine's verdict.  ``duration_ms`` should be populated by the
-            concrete implementation (wrap the inner call with a timer).
-
-        Raises
-        ------
-        PolicyEvaluationError
-            On any failure – the PDP catches this and records it.
+        """Evaluate a single access request against this policy engine.
+
+        Args:
+            subject: The authenticated user/principal requesting access.
+            action: The action being performed (e.g., "tools.invoke.db-query").
+            resource: The resource being accessed (tool, prompt, server, etc.).
+            context: Request context including IP, timestamp, session info.
+
+        Returns:
+            EngineDecision containing the verdict (ALLOW/DENY), reason,
+            matching policies, and timing information.
+
+        Raises:
+            PolicyEvaluationError: On any failure (network, timeout, invalid response).
         """
 
     # ------------------------------------------------------------------
@@ -102,8 +118,16 @@ async def evaluate(
     async def get_permissions(self, subject: Subject, context: Context) -> List[Permission]:
         """Return all permissions the subject holds according to this engine.
 
-        The default implementation returns an empty list.  Engines that can
-        enumerate permissions (e.g. Native RBAC) should override.
+        The default implementation returns an empty list. Engines that can
+        enumerate permissions (e.g., Native RBAC) should override this method.
+
+        Args:
+            subject: The authenticated user/principal to enumerate permissions for.
+            context: Request context for conditional permission evaluation.
+
+        Returns:
+            List of Permission objects representing all granted permissions.
+            Empty list if the engine does not support enumeration.
         """
         return []
 
@@ -114,9 +138,13 @@ async def get_permissions(self, subject: Subject, context: Context) -> List[Perm
     async def health_check(self) -> EngineHealthReport:
         """Probe the engine and return its health status.
 
-        The default implementation issues a trivial ``evaluate`` call with
-        dummy data and times it.  Subclasses that have a cheaper probe
-        (e.g. OPA's ``/health`` endpoint) should override.
+        The default implementation issues a trivial evaluate() call with
+        dummy data and times it. Subclasses that have a cheaper probe
+        (e.g., OPA's /health endpoint) should override this method.
+
+        Returns:
+            EngineHealthReport containing status (HEALTHY/UNHEALTHY),
+            latency in milliseconds, and optional detail message on failure.
         """
         import time
         from .pdp_models import EngineStatus

plugins/unified_pdp/cache.py

@@ -34,14 +34,23 @@
 
 
 def _build_cache_key(subject: Subject, action: str, resource: Resource, context: Context) -> str:
-    """Produce a stable, collision-resistant cache key.
+    """Produce a stable, collision-resistant cache key via SHA-256 hash.
 
     Includes all context fields that could affect policy decisions:
     - ip, session_id, user_agent for request identification
     - extra dict for policy-relevant metadata (e.g., MAC operation override)
 
     Excludes only the timestamp so requests within the same TTL window
     can hit the cache.
+
+    Args:
+        subject: The authenticated user/principal requesting access.
+        action: The action being performed (e.g., "tools.invoke.db-query").
+        resource: The resource being accessed.
+        context: Request context (IP, user_agent, session, extra metadata).
+
+    Returns:
+        A 64-character hex string (SHA-256 hash) suitable as a cache key.
     """
     payload = json.dumps(
         {
@@ -60,24 +69,61 @@ def _build_cache_key(subject: Subject, action: str, resource: Resource, context:
 
 
 class _CacheEntry:
-    """Thin wrapper that pairs a value with its expiry epoch."""
+    """Thin wrapper that pairs a cached decision with its expiry epoch.
+
+    Attributes:
+        value: The cached AccessDecision object.
+        expires_at: Monotonic timestamp when this entry expires.
+    """
 
     __slots__ = ("value", "expires_at")
 
     def __init__(self, value: AccessDecision, ttl_seconds: int):
+        """Initialize a cache entry with TTL-based expiration.
+
+        Args:
+            value: The AccessDecision to cache.
+            ttl_seconds: Time-to-live in seconds from now.
+        """
         self.value = value
         self.expires_at = time.monotonic() + ttl_seconds
 
     @property
     def expired(self) -> bool:
-        """Return True if this cache entry has exceeded its TTL."""
+        """Check if this cache entry has exceeded its TTL.
+
+        Returns:
+            True if current time exceeds expires_at, False otherwise.
+        """
         return time.monotonic() > self.expires_at
 
 
 class DecisionCache:
-    """Two-tier cache: in-memory LRU + optional async Redis."""
+    """Two-tier decision cache: in-memory LRU + optional async Redis.
+
+    The in-memory layer uses an OrderedDict for LRU eviction. When Redis is
+    configured, it acts as a write-through second tier for multi-node sharing.
+
+    Args:
+        config: Cache configuration (enabled, ttl_seconds, max_entries).
+        redis_url: Optional Redis connection URL for distributed caching.
+
+    Attributes:
+        _config: The cache configuration.
+        _store: In-memory LRU cache as OrderedDict.
+        _redis_url: Redis connection URL or None.
+        _redis: Lazy-initialized async Redis client.
+        _hits: Counter for cache hits.
+        _misses: Counter for cache misses.
+    """
 
     def __init__(self, config: CacheConfig, redis_url: Optional[str] = None):
+        """Initialize the decision cache.
+
+        Args:
+            config: Cache configuration specifying TTL, max entries, and enabled state.
+            redis_url: Optional Redis URL for distributed caching across nodes.
+        """
         self._config = config
         self._store: OrderedDict[str, _CacheEntry] = OrderedDict()
         self._redis_url = redis_url
@@ -91,7 +137,15 @@ def __init__(self, config: CacheConfig, redis_url: Optional[str] = None):
     # ------------------------------------------------------------------
 
     async def _get_redis(self):  # pragma: no cover – integration test only
-        """Lazily initialize and return the Redis client, or None if unavailable."""
+        """Lazily initialize and return the async Redis client.
+
+        Creates the Redis connection on first call if redis_url is configured.
+        Falls back to memory-only caching if the redis package is not installed.
+
+        Returns:
+            Async Redis client instance, or None if Redis is not configured
+            or the redis package is unavailable.
+        """
         if self._redis is None and self._redis_url:
             try:
                 import redis.asyncio as aioredis
@@ -114,7 +168,20 @@ async def get(
         resource: Resource,
         context: Context,
     ) -> Optional[AccessDecision]:
-        """Look up a cached decision.  Returns ``None`` on miss or expiry."""
+        """Look up a cached decision by request parameters.
+
+        Checks in-memory cache first, then falls through to Redis if configured.
+        Expired entries are lazily evicted on access. Cache hits update LRU order.
+
+        Args:
+            subject: The authenticated user/principal requesting access.
+            action: The action being performed.
+            resource: The resource being accessed.
+            context: Request context (IP, user_agent, session, extra).
+
+        Returns:
+            Cached AccessDecision if found and not expired, None otherwise.
+        """
         if not self._config.enabled:
             return None
 
@@ -155,7 +222,18 @@ async def put(
         context: Context,
         decision: AccessDecision,
     ) -> None:
-        """Store a decision.  Evicts LRU entries when the cap is reached."""
+        """Store a decision in both memory and Redis (if configured).
+
+        Evicts least-recently-used entries when max_entries is reached.
+        Writes to Redis with TTL for distributed cache sharing.
+
+        Args:
+            subject: The authenticated user/principal requesting access.
+            action: The action being performed.
+            resource: The resource being accessed.
+            context: Request context (IP, user_agent, session, extra).
+            decision: The AccessDecision to cache.
+        """
         if not self._config.enabled:
             return
 
@@ -184,9 +262,19 @@ async def invalidate(
         action: Optional[str] = None,
         resource: Optional[Resource] = None,
     ) -> int:
-        """Invalidate matching entries.  Pass ``None`` for any field to match all.
+        """Invalidate cached entries matching the given filters.
 
-        Returns the number of entries removed.
+        Pass None for any field to match all entries. Currently flushes the
+        entire cache when any filter is provided (targeted invalidation is
+        planned for a future release).
+
+        Args:
+            subject: Filter by subject, or None to match all subjects.
+            action: Filter by action, or None to match all actions.
+            resource: Filter by resource, or None to match all resources.
+
+        Returns:
+            Number of entries removed from the in-memory cache.
         """
         removed = 0
         keys_to_delete = []
@@ -226,7 +314,18 @@ async def invalidate(
     # ------------------------------------------------------------------
 
     def stats(self) -> Dict[str, Any]:
-        """Return hit/miss counters and current size."""
+        """Return cache statistics for monitoring and debugging.
+
+        Returns:
+            Dictionary containing:
+            - hits: Number of cache hits.
+            - misses: Number of cache misses.
+            - hit_rate: Ratio of hits to total requests (0.0-1.0).
+            - size: Current number of entries in memory.
+            - max_entries: Maximum allowed entries.
+            - ttl_seconds: Time-to-live for cached entries.
+            - redis_enabled: Whether Redis backing is configured.
+        """
         total = self._hits + self._misses
         return {
             "hits": self._hits,