praisonaiagents 0.0.98__tar.gz → 0.0.100__tar.gz

{praisonaiagents-0.0.98 → praisonaiagents-0.0.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praisonaiagents
-Version: 0.0.98
+Version: 0.0.100
 Summary: Praison AI agents for completing complex tasks with Self Reflection Agents
 Author: Mervin Praison
 Requires-Python: >=3.10

{praisonaiagents-0.0.98 → praisonaiagents-0.0.100}/praisonaiagents/agent/agent.py

@@ -3,7 +3,7 @@ import time
 import json
 import logging
 import asyncio
-from typing import List, Optional, Any, Dict, Union, Literal, TYPE_CHECKING
+from typing import List, Optional, Any, Dict, Union, Literal, TYPE_CHECKING, Callable, Tuple
 from rich.console import Console
 from rich.live import Live
 from openai import AsyncOpenAI
@@ -32,6 +32,7 @@ _shared_apps = {}  # Dict of port -> FastAPI app
 
 if TYPE_CHECKING:
     from ..task.task import Task
+    from ..main import TaskOutput
 
 @dataclass
 class ChatCompletionMessage:
@@ -368,7 +369,9 @@ class Agent:
         min_reflect: int = 1,
         reflect_llm: Optional[str] = None,
         user_id: Optional[str] = None,
-        reasoning_steps: bool = False
+        reasoning_steps: bool = False,
+        guardrail: Optional[Union[Callable[['TaskOutput'], Tuple[bool, Any]], str]] = None,
+        max_guardrail_retries: int = 3
     ):
         # Add check at start if memory is requested
         if memory is not None:
@@ -483,6 +486,12 @@ Your Goal: {self.goal}
         # Store user_id
         self.user_id = user_id or "praison"
         self.reasoning_steps = reasoning_steps
+        
+        # Initialize guardrail settings
+        self.guardrail = guardrail
+        self.max_guardrail_retries = max_guardrail_retries
+        self._guardrail_fn = None
+        self._setup_guardrail()
 
         # Check if knowledge parameter has any values
         if not knowledge:
@@ -512,6 +521,149 @@ Your Goal: {self.goal}
         except Exception as e:
             logging.error(f"Error processing knowledge item: {knowledge_item}, error: {e}")
 
+    def _setup_guardrail(self):
+        """Setup the guardrail function based on the provided guardrail parameter."""
+        if self.guardrail is None:
+            self._guardrail_fn = None
+            return
+            
+        if callable(self.guardrail):
+            # Validate function signature
+            sig = inspect.signature(self.guardrail)
+            positional_args = [
+                param for param in sig.parameters.values()
+                if param.default is inspect.Parameter.empty
+            ]
+            if len(positional_args) != 1:
+                raise ValueError("Agent guardrail function must accept exactly one parameter (TaskOutput)")
+            
+            # Check return annotation if present
+            from typing import get_args, get_origin
+            return_annotation = sig.return_annotation
+            if return_annotation != inspect.Signature.empty:
+                return_annotation_args = get_args(return_annotation)
+                if not (
+                    get_origin(return_annotation) is tuple
+                    and len(return_annotation_args) == 2
+                    and return_annotation_args[0] is bool
+                    and (
+                        return_annotation_args[1] is Any
+                        or return_annotation_args[1] is str
+                        or str(return_annotation_args[1]).endswith('TaskOutput')
+                        or str(return_annotation_args[1]).startswith('typing.Union')
+                    )
+                ):
+                    raise ValueError(
+                        "If return type is annotated, it must be Tuple[bool, Any] or Tuple[bool, Union[str, TaskOutput]]"
+                    )
+            
+            self._guardrail_fn = self.guardrail
+        elif isinstance(self.guardrail, str):
+            # Create LLM-based guardrail
+            from ..guardrails import LLMGuardrail
+            llm = getattr(self, 'llm', None) or getattr(self, 'llm_instance', None)
+            self._guardrail_fn = LLMGuardrail(description=self.guardrail, llm=llm)
+        else:
+            raise ValueError("Agent guardrail must be either a callable or a string description")
+
+    def _process_guardrail(self, task_output):
+        """Process the guardrail validation for a task output.
+        
+        Args:
+            task_output: The task output to validate
+            
+        Returns:
+            GuardrailResult: The result of the guardrail validation
+        """
+        from ..guardrails import GuardrailResult
+        
+        if not self._guardrail_fn:
+            return GuardrailResult(success=True, result=task_output)
+        
+        try:
+            # Call the guardrail function
+            result = self._guardrail_fn(task_output)
+            
+            # Convert the result to a GuardrailResult
+            return GuardrailResult.from_tuple(result)
+            
+        except Exception as e:
+            logging.error(f"Agent {self.name}: Error in guardrail validation: {e}")
+            # On error, return failure
+            return GuardrailResult(
+                success=False,
+                result=None,
+                error=f"Agent guardrail validation error: {str(e)}"
+            )
+
+    def _apply_guardrail_with_retry(self, response_text, prompt, temperature=0.2, tools=None):
+        """Apply guardrail validation with retry logic.
+        
+        Args:
+            response_text: The response to validate
+            prompt: Original prompt for regeneration if needed
+            temperature: Temperature for regeneration
+            tools: Tools for regeneration
+            
+        Returns:
+            str: The validated response text or None if validation fails after retries
+        """
+        if not self._guardrail_fn:
+            return response_text
+            
+        from ..main import TaskOutput
+        
+        retry_count = 0
+        current_response = response_text
+        
+        while retry_count <= self.max_guardrail_retries:
+            # Create TaskOutput object
+            task_output = TaskOutput(
+                description="Agent response output",
+                raw=current_response,
+                agent=self.name
+            )
+            
+            # Process guardrail
+            guardrail_result = self._process_guardrail(task_output)
+            
+            if guardrail_result.success:
+                logging.info(f"Agent {self.name}: Guardrail validation passed")
+                # Return the potentially modified result
+                if guardrail_result.result and hasattr(guardrail_result.result, 'raw'):
+                    return guardrail_result.result.raw
+                elif guardrail_result.result:
+                    return str(guardrail_result.result)
+                else:
+                    return current_response
+            
+            # Guardrail failed
+            if retry_count >= self.max_guardrail_retries:
+                raise Exception(
+                    f"Agent {self.name} response failed guardrail validation after {self.max_guardrail_retries} retries. "
+                    f"Last error: {guardrail_result.error}"
+                )
+            
+            retry_count += 1
+            logging.warning(f"Agent {self.name}: Guardrail validation failed (retry {retry_count}/{self.max_guardrail_retries}): {guardrail_result.error}")
+            
+            # Regenerate response for retry
+            try:
+                retry_prompt = f"{prompt}\n\nNote: Previous response failed validation due to: {guardrail_result.error}. Please provide an improved response."
+                response = self._chat_completion([{"role": "user", "content": retry_prompt}], temperature, tools)
+                if response and response.choices:
+                    current_response = response.choices[0].message.content.strip()
+                else:
+                    raise Exception("Failed to generate retry response")
+            except Exception as e:
+                logging.error(f"Agent {self.name}: Error during guardrail retry: {e}")
+                # If we can't regenerate, fail the guardrail
+                raise Exception(
+                    f"Agent {self.name} guardrail retry failed: {e}"
+                )
+        
+        return current_response
+
     def generate_task(self) -> 'Task':
         """Generate a Task object from the agent's instructions"""
         from ..task.task import Task
@@ -967,7 +1119,13 @@ Your Goal: {self.goal}
                     total_time = time.time() - start_time
                     logging.debug(f"Agent.chat completed in {total_time:.2f} seconds")
 
-                return response_text
+                # Apply guardrail validation for custom LLM response
+                try:
+                    validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                    return validated_response
+                except Exception as e:
+                    logging.error(f"Agent {self.name}: Guardrail validation failed for custom LLM: {e}")
+                    return None
             except Exception as e:
                 display_error(f"Error in LLM chat: {e}")
                 return None
@@ -1055,8 +1213,20 @@ Your Goal: {self.goal}
                         display_interaction(original_prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
                         # Return only reasoning content if reasoning_steps is True
                         if reasoning_steps and hasattr(response.choices[0].message, 'reasoning_content'):
-                            return response.choices[0].message.reasoning_content
-                        return response_text
+                            # Apply guardrail to reasoning content
+                            try:
+                                validated_reasoning = self._apply_guardrail_with_retry(response.choices[0].message.reasoning_content, original_prompt, temperature, tools)
+                                return validated_reasoning
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed for reasoning content: {e}")
+                                return None
+                        # Apply guardrail to regular response
+                        try:
+                            validated_response = self._apply_guardrail_with_retry(response_text, original_prompt, temperature, tools)
+                            return validated_response
+                        except Exception as e:
+                            logging.error(f"Agent {self.name}: Guardrail validation failed: {e}")
+                            return None
 
                     reflection_prompt = f"""
 Reflect on your previous response: '{response_text}'.
@@ -1089,7 +1259,13 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                             self.chat_history.append({"role": "user", "content": prompt})
                             self.chat_history.append({"role": "assistant", "content": response_text})
                             display_interaction(prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
-                            return response_text
+                            # Apply guardrail validation after satisfactory reflection
+                            try:
+                                validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                                return validated_response
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed after reflection: {e}")
+                                return None
 
                         # Check if we've hit max reflections
                         if reflection_count >= self.max_reflect - 1:
@@ -1098,7 +1274,13 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                             self.chat_history.append({"role": "user", "content": prompt})
                             self.chat_history.append({"role": "assistant", "content": response_text})
                             display_interaction(prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
-                            return response_text
+                            # Apply guardrail validation after max reflections
+                            try:
+                                validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                                return validated_response
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed after max reflections: {e}")
+                                return None
 
                         logging.debug(f"{self.name} reflection count {reflection_count + 1}, continuing reflection process")
                         messages.append({"role": "user", "content": "Now regenerate your response using the reflection you made"})
@@ -1122,8 +1304,16 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
         if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
             total_time = time.time() - start_time
             logging.debug(f"Agent.chat completed in {total_time:.2f} seconds")
-            
-        return response_text
+        
+        # Apply guardrail validation before returning    
+        try:
+            validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+            return validated_response
+        except Exception as e:
+            logging.error(f"Agent {self.name}: Guardrail validation failed: {e}")
+            if self.verbose:
+                display_error(f"Guardrail validation failed: {e}", console=self.console)
+            return None
 
     def clean_json_output(self, output: str) -> str:
         """Clean and extract JSON from response text."""

praisonaiagents-0.0.100/praisonaiagents/guardrails/__init__.py

@@ -0,0 +1,11 @@
+"""
+Guardrails module for PraisonAI Agents.
+
+This module provides validation and safety mechanisms for task outputs,
+including both function-based and LLM-based guardrails.
+"""
+
+from .guardrail_result import GuardrailResult
+from .llm_guardrail import LLMGuardrail
+
+__all__ = ["GuardrailResult", "LLMGuardrail"]

praisonaiagents-0.0.100/praisonaiagents/guardrails/guardrail_result.py

@@ -0,0 +1,43 @@
+"""
+Guardrail result classes for PraisonAI Agents.
+
+This module provides the result types for guardrail validation,
+following the same pattern as CrewAI for consistency.
+"""
+
+from typing import Any, Tuple, Union
+from pydantic import BaseModel, Field
+from ..main import TaskOutput
+
+
+class GuardrailResult(BaseModel):
+    """Result of a guardrail validation."""
+    
+    success: bool = Field(description="Whether the guardrail check passed")
+    result: Union[str, TaskOutput, None] = Field(description="The result if modified, or None if unchanged")
+    error: str = Field(default="", description="Error message if validation failed")
+    
+    @classmethod
+    def from_tuple(cls, result: Tuple[bool, Any]) -> "GuardrailResult":
+        """Create a GuardrailResult from a tuple returned by a guardrail function.
+        
+        Args:
+            result: Tuple of (success, result_or_error)
+            
+        Returns:
+            GuardrailResult: The structured result
+        """
+        success, data = result
+        
+        if success:
+            return cls(
+                success=True,
+                result=data,
+                error=""
+            )
+        else:
+            return cls(
+                success=False,
+                result=None,
+                error=str(data) if data else "Guardrail validation failed"
+            )

praisonaiagents-0.0.100/praisonaiagents/guardrails/llm_guardrail.py

@@ -0,0 +1,88 @@
+"""
+LLM-based guardrail implementation for PraisonAI Agents.
+
+This module provides LLM-powered guardrails that can validate task outputs
+using natural language descriptions, similar to CrewAI's implementation.
+"""
+
+import logging
+from typing import Any, Tuple, Union, Optional
+from pydantic import BaseModel
+from ..main import TaskOutput
+
+
+class LLMGuardrail:
+    """An LLM-powered guardrail that validates task outputs using natural language."""
+    
+    def __init__(self, description: str, llm: Any = None):
+        """Initialize the LLM guardrail.
+        
+        Args:
+            description: Natural language description of what to validate
+            llm: The LLM instance to use for validation
+        """
+        self.description = description
+        self.llm = llm
+        self.logger = logging.getLogger(__name__)
+    
+    def __call__(self, task_output: TaskOutput) -> Tuple[bool, Union[str, TaskOutput]]:
+        """Validate the task output using the LLM.
+        
+        Args:
+            task_output: The task output to validate
+            
+        Returns:
+            Tuple of (success, result) where result is the output or error message
+        """
+        try:
+            if not self.llm:
+                self.logger.warning("No LLM provided for guardrail validation")
+                return True, task_output
+            
+            # Create validation prompt
+            validation_prompt = f"""
+You are a quality assurance validator. Your task is to evaluate the following output against specific criteria.
+
+Validation Criteria: {self.description}
+
+Output to Validate:
+{task_output.raw}
+
+Please evaluate if this output meets the criteria. Respond with:
+1. "PASS" if the output meets all criteria
+2. "FAIL: [specific reason]" if the output does not meet criteria
+
+Your response:"""
+
+            # Get LLM response
+            if hasattr(self.llm, 'chat'):
+                # For Agent's LLM interface
+                response = self.llm.chat(validation_prompt, temperature=0.1)
+            elif hasattr(self.llm, 'get_response'):
+                # For custom LLM instances
+                response = self.llm.get_response(validation_prompt, temperature=0.1)
+            elif callable(self.llm):
+                # For simple callable LLMs
+                response = self.llm(validation_prompt)
+            else:
+                self.logger.error(f"Unsupported LLM type: {type(self.llm)}")
+                return True, task_output
+            
+            # Parse response
+            response = str(response).strip()
+            
+            if response.upper().startswith("PASS"):
+                return True, task_output
+            elif response.upper().startswith("FAIL"):
+                # Extract the reason
+                reason = response[5:].strip(": ")
+                return False, f"Guardrail validation failed: {reason}"
+            else:
+                # Unclear response, log and pass through
+                self.logger.warning(f"Unclear guardrail response: {response}")
+                return True, task_output
+                
+        except Exception as e:
+            self.logger.error(f"Error in LLM guardrail validation: {str(e)}")
+            # On error, pass through the original output
+            return True, task_output