jaf-py 2.5.10__py3-none-any.whl → 2.5.12__py3-none-any.whl

jaf/policies/handoff.py

@@ -14,24 +14,24 @@ from ..core.types import Guardrail, ValidationResult
 @dataclass
 class HandoffPolicy:
     """Policy configuration for agent handoffs."""
+
     allowed_handoffs: Dict[str, List[str]]  # source_agent -> [allowed_target_agents]
     require_permission: bool = True
     validate_context: bool = True
     max_handoff_depth: int = 10
 
+
 def create_handoff_guardrail(
-    policy: HandoffPolicy,
-    current_agent: str,
-    handoff_history: Optional[List[str]] = None
+    policy: HandoffPolicy, current_agent: str, handoff_history: Optional[List[str]] = None
 ) -> Guardrail:
     """
     Create a guardrail that validates agent handoffs.
-    
+
     Args:
         policy: Handoff policy configuration
         current_agent: Name of the current agent
         handoff_history: List of previous agents in the current session
-        
+
     Returns:
         Guardrail function for handoff validation
     """
@@ -40,20 +40,16 @@ def create_handoff_guardrail(
     def handoff_guardrail(handoff_data: Any) -> ValidationResult:
         # Extract target agent from handoff data
         if isinstance(handoff_data, dict):
-            target_agent = handoff_data.get('handoff_to') or handoff_data.get('target_agent')
+            target_agent = handoff_data.get("handoff_to") or handoff_data.get("target_agent")
         elif isinstance(handoff_data, str):
             # Assume the string is the target agent name
             target_agent = handoff_data
         else:
-            return ValidationResult(
-                is_valid=False,
-                error_message="Invalid handoff data format"
-            )
+            return ValidationResult(is_valid=False, error_message="Invalid handoff data format")
 
         if not target_agent:
             return ValidationResult(
-                is_valid=False,
-                error_message="No target agent specified in handoff"
+                is_valid=False, error_message="No target agent specified in handoff"
             )
 
         # Check permission
@@ -62,49 +58,47 @@ def create_handoff_guardrail(
             if target_agent not in allowed_targets:
                 return ValidationResult(
                     is_valid=False,
-                    error_message=f"Agent {current_agent} is not allowed to handoff to {target_agent}"
+                    error_message=f"Agent {current_agent} is not allowed to handoff to {target_agent}",
                 )
 
         # Check handoff depth to prevent infinite loops
         if len(handoff_history) >= policy.max_handoff_depth:
             return ValidationResult(
                 is_valid=False,
-                error_message=f"Maximum handoff depth ({policy.max_handoff_depth}) exceeded"
+                error_message=f"Maximum handoff depth ({policy.max_handoff_depth}) exceeded",
             )
 
         # Check for immediate circular handoffs
         if handoff_history and handoff_history[-1] == target_agent:
             return ValidationResult(
                 is_valid=False,
-                error_message=f"Circular handoff detected: {current_agent} -> {target_agent} -> {current_agent}"
+                error_message=f"Circular handoff detected: {current_agent} -> {target_agent} -> {current_agent}",
             )
 
         # Validate context if required
         if policy.validate_context and isinstance(handoff_data, dict):
-            context = handoff_data.get('context', {})
+            context = handoff_data.get("context", {})
             if not isinstance(context, dict):
                 return ValidationResult(
-                    is_valid=False,
-                    error_message="Handoff context must be a dictionary"
+                    is_valid=False, error_message="Handoff context must be a dictionary"
                 )
 
         return ValidationResult(is_valid=True)
 
     return handoff_guardrail
 
+
 def validate_handoff_permissions(
-    source_agent: str,
-    target_agent: str,
-    allowed_handoffs: Dict[str, List[str]]
+    source_agent: str, target_agent: str, allowed_handoffs: Dict[str, List[str]]
 ) -> ValidationResult:
     """
     Validate if a handoff is allowed between two agents.
-    
+
     Args:
         source_agent: Name of the source agent
         target_agent: Name of the target agent
         allowed_handoffs: Dictionary mapping source agents to allowed targets
-        
+
     Returns:
         ValidationResult indicating if the handoff is allowed
     """
@@ -113,22 +107,23 @@ def validate_handoff_permissions(
     if target_agent not in allowed_targets:
         return ValidationResult(
             is_valid=False,
-            error_message=f"Handoff from {source_agent} to {target_agent} not permitted"
+            error_message=f"Handoff from {source_agent} to {target_agent} not permitted",
         )
 
     return ValidationResult(is_valid=True)
 
+
 def create_role_based_handoff_policy(
     agent_roles: Dict[str, str],  # agent_name -> role
-    role_permissions: Dict[str, List[str]]  # role -> [allowed_target_roles]
+    role_permissions: Dict[str, List[str]],  # role -> [allowed_target_roles]
 ) -> HandoffPolicy:
     """
     Create a handoff policy based on agent roles.
-    
+
     Args:
         agent_roles: Mapping of agent names to their roles
         role_permissions: Mapping of roles to allowed target roles
-        
+
     Returns:
         HandoffPolicy configured for role-based permissions
     """
@@ -137,27 +132,27 @@ def create_role_based_handoff_policy(
     for agent_name, agent_role in agent_roles.items():
         allowed_target_roles = role_permissions.get(agent_role, [])
         allowed_targets = [
-            target_agent for target_agent, target_role in agent_roles.items()
+            target_agent
+            for target_agent, target_role in agent_roles.items()
             if target_role in allowed_target_roles and target_agent != agent_name
         ]
         allowed_handoffs[agent_name] = allowed_targets
 
     return HandoffPolicy(
-        allowed_handoffs=allowed_handoffs,
-        require_permission=True,
-        validate_context=True
+        allowed_handoffs=allowed_handoffs, require_permission=True, validate_context=True
     )
 
+
 def create_workflow_handoff_policy(
-    workflow_steps: List[List[str]]  # List of workflow steps, each step is a list of agent names
+    workflow_steps: List[List[str]],  # List of workflow steps, each step is a list of agent names
 ) -> HandoffPolicy:
     """
     Create a handoff policy based on a defined workflow.
-    
+
     Args:
         workflow_steps: List of workflow steps, where each step contains agent names
                        that can transition to agents in the next step
-        
+
     Returns:
         HandoffPolicy configured for workflow-based transitions
     """
@@ -180,14 +175,13 @@ def create_workflow_handoff_policy(
             allowed_handoffs[agent] = allowed_targets
 
     return HandoffPolicy(
-        allowed_handoffs=allowed_handoffs,
-        require_permission=True,
-        validate_context=True
+        allowed_handoffs=allowed_handoffs, require_permission=True, validate_context=True
     )
 
+
 # Predefined policies for common scenarios
 def create_hierarchical_handoff_policy(
-    hierarchy: Dict[str, List[str]]  # supervisor -> [subordinates]
+    hierarchy: Dict[str, List[str]],  # supervisor -> [subordinates]
 ) -> HandoffPolicy:
     """Create a policy for hierarchical agent handoffs."""
     allowed_handoffs = {}
@@ -214,11 +208,10 @@ def create_hierarchical_handoff_policy(
         allowed_handoffs[subordinate] = supervisors + list(siblings)
 
     return HandoffPolicy(
-        allowed_handoffs=allowed_handoffs,
-        require_permission=True,
-        validate_context=True
+        allowed_handoffs=allowed_handoffs, require_permission=True, validate_context=True
     )
 
+
 def create_open_handoff_policy(agent_names: List[str]) -> HandoffPolicy:
     """Create a policy that allows any agent to handoff to any other agent."""
     allowed_handoffs = {}
@@ -229,14 +222,12 @@ def create_open_handoff_policy(agent_names: List[str]) -> HandoffPolicy:
     return HandoffPolicy(
         allowed_handoffs=allowed_handoffs,
         require_permission=False,  # Open policy
-        validate_context=False
+        validate_context=False,
     )
 
+
 def create_restricted_handoff_policy() -> HandoffPolicy:
     """Create a policy that doesn't allow any handoffs."""
     return HandoffPolicy(
-        allowed_handoffs={},
-        require_permission=True,
-        validate_context=True,
-        max_handoff_depth=0
+        allowed_handoffs={}, require_permission=True, validate_context=True, max_handoff_depth=0
     )

jaf/policies/validation.py

@@ -19,23 +19,23 @@ from ..core.types import Guardrail, InvalidValidationResult, ValidationResult, V
 @dataclass
 class GuardrailConfig:
     """Configuration for guardrails."""
+
     enabled: bool = True
     strict_mode: bool = False
     custom_message: Optional[str] = None
 
+
 def create_length_guardrail(
-    max_length: int,
-    min_length: int = 0,
-    config: Optional[GuardrailConfig] = None
+    max_length: int, min_length: int = 0, config: Optional[GuardrailConfig] = None
 ) -> Guardrail:
     """
     Create a guardrail that validates text length.
-    
+
     Args:
         max_length: Maximum allowed length
         min_length: Minimum required length
         config: Optional guardrail configuration
-        
+
     Returns:
         Guardrail function
     """
@@ -48,34 +48,37 @@ def create_length_guardrail(
         text_length = len(text)
 
         if text_length > max_length:
-            message = (config.custom_message or
-                      f"Text length {text_length} exceeds maximum {max_length}")
+            message = (
+                config.custom_message or f"Text length {text_length} exceeds maximum {max_length}"
+            )
             return InvalidValidationResult(error_message=message)
 
         if text_length < min_length:
-            message = (config.custom_message or
-                      f"Text length {text_length} below minimum {min_length}")
+            message = (
+                config.custom_message or f"Text length {text_length} below minimum {min_length}"
+            )
             return InvalidValidationResult(error_message=message)
 
         return ValidValidationResult()
 
     return length_guardrail
 
+
 def create_content_filter_guardrail(
     blocked_patterns: List[str],
     allowed_patterns: Optional[List[str]] = None,
     case_sensitive: bool = False,
-    config: Optional[GuardrailConfig] = None
+    config: Optional[GuardrailConfig] = None,
 ) -> Guardrail:
     """
     Create a guardrail that filters content based on patterns.
-    
+
     Args:
         blocked_patterns: Regex patterns that should be blocked
         allowed_patterns: Regex patterns that override blocks (allowlist)
         case_sensitive: Whether pattern matching is case sensitive
         config: Optional guardrail configuration
-        
+
     Returns:
         Guardrail function
     """
@@ -84,8 +87,9 @@ def create_content_filter_guardrail(
     # Compile patterns for efficiency
     flags = 0 if case_sensitive else re.IGNORECASE
     compiled_blocked = [re.compile(pattern, flags) for pattern in blocked_patterns]
-    compiled_allowed = ([re.compile(pattern, flags) for pattern in allowed_patterns]
-                       if allowed_patterns else [])
+    compiled_allowed = (
+        [re.compile(pattern, flags) for pattern in allowed_patterns] if allowed_patterns else []
+    )
 
     def content_filter_guardrail(text: str) -> ValidationResult:
         if not config.enabled:
@@ -98,25 +102,26 @@ def create_content_filter_guardrail(
                 is_allowed = any(allowed.search(text) for allowed in compiled_allowed)
 
                 if not is_allowed:
-                    message = (config.custom_message or
-                              f"Content blocked by pattern: {pattern.pattern}")
+                    message = (
+                        config.custom_message or f"Content blocked by pattern: {pattern.pattern}"
+                    )
                     return InvalidValidationResult(error_message=message)
 
         return ValidValidationResult()
 
     return content_filter_guardrail
 
+
 def create_json_validation_guardrail(
-    schema_class: type[BaseModel],
-    config: Optional[GuardrailConfig] = None
+    schema_class: type[BaseModel], config: Optional[GuardrailConfig] = None
 ) -> Guardrail:
     """
     Create a guardrail that validates JSON against a Pydantic schema.
-    
+
     Args:
         schema_class: Pydantic model class for validation
         config: Optional guardrail configuration
-        
+
     Returns:
         Guardrail function
     """
@@ -132,8 +137,7 @@ def create_json_validation_guardrail(
                 try:
                     data = json.loads(data)
                 except json.JSONDecodeError as e:
-                    message = (config.custom_message or
-                              f"Invalid JSON format: {e!s}")
+                    message = config.custom_message or f"Invalid JSON format: {e!s}"
                     return InvalidValidationResult(error_message=message)
 
             # Validate against schema
@@ -141,36 +145,37 @@ def create_json_validation_guardrail(
             return ValidValidationResult()
 
         except ValidationError as e:
-            message = (config.custom_message or
-                      f"Schema validation failed: {e!s}")
+            message = config.custom_message or f"Schema validation failed: {e!s}"
             return InvalidValidationResult(error_message=message)
         except Exception as e:
-            message = (config.custom_message or
-                      f"Validation error: {e!s}")
+            message = config.custom_message or f"Validation error: {e!s}"
             return InvalidValidationResult(error_message=message)
 
     return json_validation_guardrail
 
+
 @dataclass
 class RateLimitState:
     """State for rate limiting."""
+
     calls: List[float] = field(default_factory=list)
     window_size: float = 60.0  # seconds
     max_calls: int = 10
 
+
 def create_rate_limit_guardrail(
     max_calls: int = 10,
     window_size: float = 60.0,  # seconds
-    config: Optional[GuardrailConfig] = None
+    config: Optional[GuardrailConfig] = None,
 ) -> Guardrail:
     """
     Create a guardrail that implements rate limiting.
-    
+
     Args:
         max_calls: Maximum number of calls allowed in the window
         window_size: Time window in seconds
         config: Optional guardrail configuration
-        
+
     Returns:
         Guardrail function
     """
@@ -189,8 +194,10 @@ def create_rate_limit_guardrail(
 
         # Check if we're at the limit
         if len(state.calls) >= state.max_calls:
-            message = (config.custom_message or
-                      f"Rate limit exceeded: {len(state.calls)}/{state.max_calls} calls in {state.window_size}s")
+            message = (
+                config.custom_message
+                or f"Rate limit exceeded: {len(state.calls)}/{state.max_calls} calls in {state.window_size}s"
+            )
             return InvalidValidationResult(error_message=message)
 
         # Record this call
@@ -199,19 +206,18 @@ def create_rate_limit_guardrail(
 
     return rate_limit_guardrail
 
+
 def combine_guardrails(
-    guardrails: List[Guardrail],
-    require_all: bool = True,
-    config: Optional[GuardrailConfig] = None
+    guardrails: List[Guardrail], require_all: bool = True, config: Optional[GuardrailConfig] = None
 ) -> Guardrail:
     """
     Combine multiple guardrails into a single guardrail.
-    
+
     Args:
         guardrails: List of guardrails to combine
         require_all: If True, all guardrails must pass; if False, at least one must pass
         config: Optional guardrail configuration
-        
+
     Returns:
         Combined guardrail function
     """
@@ -228,7 +234,7 @@ def combine_guardrails(
                 # Handle both sync and async guardrails
                 if callable(guardrail):
                     result = guardrail(data)
-                    if hasattr(result, '__await__'):
+                    if hasattr(result, "__await__"):
                         result = await result
                 else:
                     continue
@@ -265,24 +271,36 @@ def combine_guardrails(
 
     return combined_guardrail
 
+
 # Common guardrail presets
 def create_safe_text_guardrail(config: Optional[GuardrailConfig] = None) -> Guardrail:
     """Create a guardrail for safe text content."""
-    return combine_guardrails([
-        create_length_guardrail(max_length=10000, min_length=1),
-        create_content_filter_guardrail([
-            r'<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>',  # Script tags
-            r'javascript:',  # JavaScript URLs
-            r'data:.*base64',  # Base64 data URLs
-        ], case_sensitive=False)
-    ], config=config)
+    return combine_guardrails(
+        [
+            create_length_guardrail(max_length=10000, min_length=1),
+            create_content_filter_guardrail(
+                [
+                    r"<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>",  # Script tags
+                    r"javascript:",  # JavaScript URLs
+                    r"data:.*base64",  # Base64 data URLs
+                ],
+                case_sensitive=False,
+            ),
+        ],
+        config=config,
+    )
+
 
 def create_api_input_guardrail(config: Optional[GuardrailConfig] = None) -> Guardrail:
     """Create a guardrail for API input validation."""
-    return combine_guardrails([
-        create_length_guardrail(max_length=50000),
-        create_rate_limit_guardrail(max_calls=100, window_size=60),
-    ], config=config)
+    return combine_guardrails(
+        [
+            create_length_guardrail(max_length=50000),
+            create_rate_limit_guardrail(max_calls=100, window_size=60),
+        ],
+        config=config,
+    )
+
 
 # Compatibility aliases for tests
 def create_content_filter(blocked_patterns: List[str], **kwargs) -> Guardrail:
@@ -290,7 +308,7 @@ def create_content_filter(blocked_patterns: List[str], **kwargs) -> Guardrail:
     guardrail = create_content_filter_guardrail(
         blocked_patterns,
         config=GuardrailConfig(custom_message="Contains inappropriate content"),
-        **kwargs
+        **kwargs,
     )
 
     async def async_wrapper(text: str) -> ValidationResult:
@@ -298,18 +316,24 @@ def create_content_filter(blocked_patterns: List[str], **kwargs) -> Guardrail:
 
     return async_wrapper
 
+
 def create_length_limiter(max_length: int, min_length: int = 0, **kwargs) -> Guardrail:
     """Create length limiter (test compatibility)."""
 
     async def async_wrapper(text: str) -> ValidationResult:
         if len(text) > max_length:
-            return InvalidValidationResult(error_message=f"Text exceeds maximum length of {max_length}")
+            return InvalidValidationResult(
+                error_message=f"Text exceeds maximum length of {max_length}"
+            )
         if len(text) < min_length:
-            return InvalidValidationResult(error_message=f"Text below minimum length of {min_length}")
+            return InvalidValidationResult(
+                error_message=f"Text below minimum length of {min_length}"
+            )
         return ValidValidationResult()
 
     return async_wrapper
 
+
 def create_format_validator(schema_class: type[BaseModel], **kwargs) -> Guardrail:
     """Create format validator (test compatibility)."""
     guardrail = create_json_validation_guardrail(schema_class, **kwargs)

jaf/providers/__init__.py

@@ -21,12 +21,13 @@ _DEPRECATED_ALIASES = {
 _REMOVED_EXPORTS = {
     # No safe automatic migration known — force an explicit choice.
     "MCPClient": "MCPClient was removed. Use transport-specific tool factories: "
-                 "create_mcp_stdio_tools, create_mcp_sse_tools, or create_mcp_http_tools.",
+    "create_mcp_stdio_tools, create_mcp_sse_tools, or create_mcp_http_tools.",
     "create_mcp_tools_from_client": "create_mcp_tools_from_client was removed. "
-                                    "Construct tools via create_mcp_stdio_tools, "
-                                    "create_mcp_sse_tools, or create_mcp_http_tools as appropriate.",
+    "Construct tools via create_mcp_stdio_tools, "
+    "create_mcp_sse_tools, or create_mcp_http_tools as appropriate.",
 }
 
+
 def __getattr__(name: str):
     if name in _DEPRECATED_ALIASES:
         obj, new_name = _DEPRECATED_ALIASES[name]
@@ -46,10 +47,12 @@ def __getattr__(name: str):
         raise AttributeError(f"{name} has been removed")
     raise AttributeError(name)
 
+
 def __dir__():
     # Make deprecated names discoverable in REPLs without advertising in __all__
     return sorted(set(globals()) | set(_DEPRECATED_ALIASES))
 
+
 __all__ = [
     "FastMCPTool",
     "MCPToolArgs",