fix: renaming TaskGuardrail to LLMGuardrail

[lucasgomide]

I forgot to resolve this opened topic before merging

[mplachta]

Disclaimer: This review was made by a crew of AI Agents.

Code Review for PR #2731: Renaming TaskGuardrail to LLMGuardrail

---

Summary of Key Findings

This pull request implements a widespread and coherent renaming of the TaskGuardrail concept to LLMGuardrail throughout the repository, covering:

• Source code: class names, imports, method calls, and event usages.
• Event system: event classes and emitted event types.
• Documentation: conceptual explanations and examples.
• Tests: import updates and event subscriptions.

The renaming clarifies that the guardrail validation mechanism pertains specifically to outputs from Large Language Models (LLMs), thus enhancing semantic clarity and conceptual precision.

No functional code changes or regressions were introduced in this refactor. The patch maintains consistency across the codebase and tests, keeping the system behavior intact.

---

Detailed Review & Improvement Suggestions

1. Source Code (src/crewai/task.py, src/crewai/tasks/llm_guardrail.py)

• Conditional Import Handling:
  Imports for the LLMGuardrail class remain conditional inside functions, likely to avoid circular dependencies.
  Suggestion: If circular imports are not an issue, consider moving these to the top of the modules to improve readability and enable better static analysis tools support.

• Backward Compatibility:
  Since this renaming is breaking in terms of import paths and usage, provide a deprecated alias to ease transition for external clients or user code:

  # In src/crewai/tasks/llm_guardrail.py
  import warnings
  
  class LLMGuardrail:
      ...
  
  class TaskGuardrail(LLMGuardrail):
      def __init__(self, *args, **kwargs):
          warnings.warn(
              "TaskGuardrail is deprecated, use LLMGuardrail instead.",
              DeprecationWarning,
              stacklevel=2,
          )
          super().__init__(*args, **kwargs)

  This allows legacy imports with clear deprecation notices before eventual removal.

• Docstring Enhancement:
  Enhance LLMGuardrail docstrings to explicitly mark that this guardrail implementation is LLM-specific, guiding future development and usage:

  class LLMGuardrail:
      """Validates task output specifically using a Large Language Model (LLM).
  
      Note: This guardrail currently supports only LLM-based validation.
      """

---

2. Event System (src/crewai/utilities/events/llm_guardrail_events.py and related)

• The renaming of event classes from TaskGuardrail*Event to LLMGuardrail*Event is consistent and well applied.

• Docstring Clarification:
  Update event class docstrings for precision, emphasizing that events relate to LLM guardrail validations:

  class LLMGuardrailStartedEvent(BaseEvent):
      """Event emitted when an LLM guardrail validation starts."""
      ...
  
  class LLMGuardrailCompletedEvent(BaseEvent):
      """Event emitted when an LLM guardrail validation completes."""
      ...

• Event Type Strings:
  Changed from "task_guardrail_started" to "llm_guardrail_started", and similarly for completions, to maintain consistent semantic naming.

---

3. Documentation (docs/concepts/tasks.mdx)

• All references to TaskGuardrail were updated correctly to LLMGuardrail, including section headers and examples.

• Recommendation:
  Perform a comprehensive search through all docs and tutorials to ensure every instance is updated to avoid user confusion.

---

4. Tests (tests/test_task_guardrails.py)

• Tests updated well for class and event renames.

• Filename Suggestion:
  Rename the test file for consistency with the new terminology:

  git mv tests/test_task_guardrails.py tests/test_llm_guardrails.py

• Consider updating fixtures, variables, and function names that still reference task_guardrail for clarity.

• Test coverage and intent remain properly preserved.

---

Historical Context and Learnings

This renaming reflects a crucial evolution in naming conventions in the crewAIInc/crewAI codebase, distinguishing the guardrail concept as specifically tied to LLM validations rather than generic task outputs. Such clarifications prevent misuse and improve code comprehension.

Historically, renames of this nature require cross-cutting changes in event systems, documentation, and tests, all properly handled here. The suggested deprecation approaches and file renaming build upon best practices observed in other refactor PRs to support users during transitions.

---

Summary

This PR is a well-executed, consistent, and comprehensive rename refactor of the TaskGuardrail concept to LLMGuardrail across the codebase, with ample test coverage and documentation adjustments.

Recommendations Before Merging

• Add a deprecated alias for TaskGuardrail to LLMGuardrail with warnings to ease user transitions.
• Rename the test file from test_task_guardrails.py to test_llm_guardrails.py to reflect the updated terminology.
• Clarify event class docstrings to explicitly indicate LLM-specific validation events.
• Review documentation and tutorial files beyond this patch for any stale TaskGuardrail references.
• Evaluate import placements in task.py and related modules for possible static imports if circular dependencies are not a concern.

After these small refinements, this PR will be ready to merge, providing clearer naming and better developer and user experience overall.

---

Thank you for the clear and thorough changes! The code quality and overall approach are strong and maintainable.

[joaomdmoura]

Disclaimer: This review was made by a crew of AI Agents.

Code Review Comment: LLMGuardrail Renaming

Overview
This pull request effectively renames TaskGuardrail to LLMGuardrail across multiple files, thereby aligning the component name with its functionality of leveraging Language Learning Models (LLMs) for validation tasks. This is a positive change that enhances clarity in the codebase.

---

Detailed Review

1. Documentation Updates (File: docs/concepts/tasks.mdx):

   • The documentation updates reflect the renaming accurately.
   • Suggestions:
     • Add a comprehensive migration guide to assist users in transitioning smoothly from TaskGuardrail to LLMGuardrail.
     • More context about why this renaming was necessary can help users understand the evolution of the codebase.

   Example Update:

   ### LLMGuardrail (formerly TaskGuardrail)
   
   The `LLMGuardrail` class (renamed from TaskGuardrail) offers a robust mechanism for validating task outputs using Language Learning Models (LLMs).
   
   > **Migration Note**: If you're upgrading from a previous version, replace all instances of `TaskGuardrail` with `LLMGuardrail`.

2. Code Quality and Clarity (File: src/crewai/task.py):

   • The changes to import statements and class references are necessary and well-executed.
   • Suggestions:
     • Consider adding type hints to enhance code readability and provide better type checking.
     • Include a deprecation warning for the old class name to notify users of the transition.

   Example Improvement:

   from typing import Optional, Callable
   from crewai.tasks.llm_guardrail import LLMGuardrail
   
   def ensure_guardrail_is_callable(self) -> "Task":
       """Ensures the guardrail is callable and properly configured."""
       if callable(self.guardrail):
           self._guardrail = self.guardrail
       elif isinstance(self.guardrail, str):
           assert self.agent is not None
           self._guardrail = LLMGuardrail(
               description=self.guardrail,
               llm=self.agent.llm
           )
       return self

3. Error Handling Improvements (File: src/crewai/tasks/llm_guardrail.py):

   • The renaming of the main class is well done, but additional error handling is necessary to ensure robust operations.
   • Suggestions:
     • Add comprehensive error handling for invalid LLM configurations.
     • Raise appropriate exceptions in crowded functional areas (e.g., within the constructor).

   Example Update:

   class LLMGuardrail:
       """Validates task output using Language Learning Models."""
   
       def __init__(self, description: str, llm: LLM) -> None:
           if not llm:
               raise ValueError("LLM instance must be provided")
           self.description = description
           self.llm = llm

4. Event Documentation (Event-related files):

   • The renaming of event classes and types has been executed correctly.
   • Suggestions:
     • Add documentation for events to clarify their usage.
     • Implement interfaces for events to improve maintainability and flexibility down the line.

   Example Addition:

   class LLMGuardrailStartedEvent(BaseEvent):
       """Event emitted when an LLM guardrail validation starts."""
       type: str = "llm_guardrail_started"
       guardrail: Union[str, Callable]
       retry_count: int

---

General Recommendations

1. Testing:

   • Consider expanding test coverage, particularly for edge cases and integration tests with various LLM providers.
   • Adding performance benchmarks can provide valuable insights into the efficiency of the new design.

2. Future Considerations:

   • Implement a factory pattern for guardrail creation for better scalability in supporting additional guardrail types.
   • Explore the potential for async support within guardrail validations to improve concurrency management.

---

Conclusion

This pull request marks an important transition from TaskGuardrail to LLMGuardrail, aptly reflecting its new purpose. While the implementation is solid, further enhancement in documentation and error handling will significantly elevate code quality.

Impact Assessment:

• Breaking Change: Yes (requires updates to existing implementations).
• Documentation Impact: High (requires significant updates and user guidance).
• Maintenance: Low long-term impact anticipated, assuming documentation and features are upheld.

Great work on these improvements! Once the suggestions are incorporated, it will significantly enhance the quality and maintainability of the codebase.

[greysonlalonde]