Amsha 3.0.0__py3-none-any.whl

amsha/common/__init__.py

@@ -0,0 +1,4 @@
+"""Common utilities for Amsha."""
+from amsha.common.logger import get_logger, reset_logger, log_execution, MetricsLogger
+
+__all__ = ["get_logger", "reset_logger", "log_execution", "MetricsLogger"]

amsha/common/logger.py

@@ -0,0 +1,273 @@
+"""
+Comprehensive logging for Amsha (stdlib-only).
+
+This module provides structured logging with metrics tracking, execution tracing,
+and performance monitoring - going beyond simple print replacement.
+
+Basic Usage:
+    from amsha.common.logger import get_logger, log_execution, MetricsLogger
+    
+    logger = get_logger("crew_forge")
+    logger.info("Operation successful", extra={"crew_name": "test", "tokens": 1500})
+    
+    @log_execution(logger, "build_crew")
+    def build_crew(name):
+        # Automatically logs start, duration, and completion
+        pass
+"""
+from typing import Optional, Dict, Any, Callable
+import logging
+import os
+import time
+import functools
+from logging.handlers import RotatingFileHandler
+
+_configured = False
+_module_loggers: dict = {}
+
+
+# ============================================================================
+# Structured Logging Formatter
+# ============================================================================
+
+class StructuredFormatter(logging.Formatter):
+    """
+    Custom formatter that includes extra fields in log output.
+    
+    Formats log records to show structured metadata in a readable way:
+    timestamp | logger_name | level | message | key1=value1 key2=value2
+    """
+    
+    # Standard logging record attributes to exclude from extra fields
+    EXCLUDED_ATTRS = {
+        'name', 'msg', 'args', 'created', 'filename', 'funcName', 'levelname',
+        'levelno', 'lineno', 'module', 'msecs', 'message', 'pathname', 'process',
+        'processName', 'relativeCreated', 'thread', 'threadName', 'exc_info',
+        'exc_text', 'stack_info', 'asctime', 'taskName'
+    }
+    
+    def format(self, record: logging.LogRecord) -> str:
+        # Format base message with standard format
+        base_message = super().format(record)
+        
+        # Extract extra fields
+        extra_fields = {}
+        for key, value in record.__dict__.items():
+            if key not in self.EXCLUDED_ATTRS:
+                extra_fields[key] = value
+        
+        # If there are extra fields, append them to the message
+        if extra_fields:
+            # Format extra fields as key=value pairs
+            extra_str = " | ".join(f"{k}={v}" for k, v in sorted(extra_fields.items()))
+            return f"{base_message} | {extra_str}"
+        
+        return base_message
+
+
+def _configure() -> None:
+    """
+    Configure the root Amsha logger with a rotating file handler and console handler.
+    Idempotent - only runs once per process.
+    """
+    global _configured
+    if _configured:
+        return
+
+    level = os.getenv("AMSHA_LOG_LEVEL", "INFO")
+    root = logging.getLogger("Amsha")
+    root.setLevel(level.upper())
+    root.propagate = False
+
+    formatter = StructuredFormatter(
+        fmt='%(asctime)s | %(name)s | %(levelname)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+
+    logs_dir = os.getenv("AMSHA_LOG_DIR", "logs")
+    os.makedirs(logs_dir, exist_ok=True)
+
+    file_handler = RotatingFileHandler(
+        os.path.join(logs_dir, "amsha.log"),
+        maxBytes=50 * 1024 * 1024,
+        backupCount=30,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+    root.addHandler(file_handler)
+
+    # Only add a console handler if one isn't already attached (avoids duplicate
+    # console output when the root handler is configured elsewhere).
+    if not any(isinstance(h, logging.StreamHandler) for h in root.handlers):
+        console = logging.StreamHandler()
+        console.setFormatter(formatter)
+        root.addHandler(console)
+
+    _configured = True
+
+
+def get_logger(module_name: Optional[str] = None, log_level: Optional[str] = None) -> logging.Logger:
+    """
+    Get or create a logger instance for Amsha.
+    
+    All logs are written to logs/amsha.log and console (path overridable via
+    the AMSHA_LOG_DIR environment variable).
+    
+    Args:
+        module_name: Optional module name for hierarchical logging (e.g., "crew_forge")
+        log_level: Optional log level override (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+                  Defaults to environment variable AMSHA_LOG_LEVEL or INFO
+        
+    Returns:
+        Configured logger instance
+        
+    Examples:
+        >>> logger = get_logger()  # Root Amsha logger
+        >>> logger.info("Application started")
+        
+        >>> crew_logger = get_logger("crew_forge")
+        >>> crew_logger.debug("Building crew", extra={"crew_name": "test", "tokens": 1500})
+    """
+    global _module_loggers
+    
+    _configure()
+    
+    logger = logging.getLogger(f"Amsha.{module_name}" if module_name else "Amsha")
+    
+    if log_level:
+        logger.setLevel(log_level.upper())
+    
+    # Cache module loggers to avoid recreation
+    if module_name and module_name not in _module_loggers:
+        _module_loggers[module_name] = logger
+    
+    return logger
+
+
+def log_execution(logger: logging.Logger, operation_name: str) -> Callable:
+    """
+    Decorator to automatically log function execution with timing and error handling.
+    
+    Args:
+        logger: Logger instance to use
+        operation_name: Human-readable operation name
+        
+    Returns:
+        Decorated function
+        
+    Usage:
+        @log_execution(logger, "build_crew")
+        def build_atomic_crew(self, crew_name):
+            # Automatically logs start, duration, success/failure
+            return crew
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            start_time = time.time()
+            logger.debug(f"{operation_name} started", extra={
+                "operation": operation_name,
+                "function": func.__name__
+            })
+            
+            try:
+                result = func(*args, **kwargs)
+                duration = time.time() - start_time
+                
+                logger.info(f"{operation_name} completed", extra={
+                    "operation": operation_name,
+                    "duration_seconds": round(duration, 4),
+                    "status": "success"
+                })
+                return result
+            except Exception as e:
+                duration = time.time() - start_time
+                logger.error(f"{operation_name} failed", extra={
+                    "operation": operation_name,
+                    "duration_seconds": round(duration, 4),
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "status": "failed"
+                }, exc_info=True)
+                raise
+        return wrapper
+    return decorator
+
+
+class MetricsLogger:
+    """Helper class for logging structured metrics and performance data."""
+    
+    def __init__(self, logger: logging.Logger):
+        self.logger = logger
+    
+    def log_execution_metrics(self, crew_name: str, execution_id: str, 
+                             metrics: Dict[str, Any], duration: float):
+        """
+        Log comprehensive execution metrics.
+        
+        Args:
+            crew_name: Name of the crew
+            execution_id: Unique execution identifier
+            metrics: Dict containing general and gpu metrics
+            duration: Execution duration in seconds
+        """
+        general = metrics.get("general", {})
+        self.logger.info("Execution metrics captured", extra={
+            "crew_name": crew_name,
+            "execution_id": execution_id,
+            "duration_seconds": round(duration, 4),
+            "total_tokens": general.get("total_tokens", 0),
+            "prompt_tokens": general.get("prompt_tokens", 0),
+            "completion_tokens": general.get("completion_tokens", 0),
+            "cpu_usage_percent": general.get("cpu_usage_end_percent", 0),
+            "memory_change_mb": general.get("memory_usage_change_mb", 0),
+            "has_gpu_metrics": bool(metrics.get("gpu", {}))
+        })
+    
+    def log_llm_config(self, model_name: str, config: Dict[str, Any]):
+        """
+        Log LLM configuration details.
+        
+        Args:
+            model_name: Clean model name
+            config: Dict containing LLM configuration
+        """
+        self.logger.info("LLM configuration applied", extra={
+            "model_name": model_name,
+            "model": config.get("model"),
+            "temperature": config.get("temperature"),
+            "top_p": config.get("top_p"),
+            "max_tokens": config.get("max_completion_tokens"),
+            "stream": config.get("stream", False),
+            "has_base_url": bool(config.get("base_url") or config.get("endpoint"))
+        })
+    
+    def log_file_operation(self, operation: str, file_path: str, 
+                          status: str, **extra_data):
+        """
+        Log file I/O operations with context.
+        
+        Args:
+            operation: Operation type (e.g., "validation", "save", "clean")
+            file_path: Path to the file
+            status: Operation status (success, failed)
+            **extra_data: Additional context
+        """
+        self.logger.info(f"File operation: {operation}", extra={
+            "operation": operation,
+            "file_path": file_path,
+            "status": status,
+            **extra_data
+        })
+
+
+def reset_logger():
+    """
+    Reset the logger configuration. Primarily for testing purposes.
+    """
+    global _configured, _module_loggers
+    root = logging.getLogger("Amsha")
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    _configured = False
+    _module_loggers = {}

amsha/configuration/application/configuration_manager.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+from typing import Union, Dict, Any, Type, TypeVar
+import json
+import yaml
+
+from pydantic import BaseModel
+from amsha.configuration.infrastructure.strict_validator import StrictConfigValidator
+from amsha.configuration.exceptions.amsha_configuration_exception import AmshaConfigurationException
+
+T = TypeVar('T', bound=BaseModel)
+
+class ConfigurationManager:
+    """
+    Manages loading and strict validation of Amsha Configurations.
+    Requires configurations to be perfectly valid to proceed.
+    """
+    
+    @staticmethod
+    def load_from_dict(model_class: Type[T], data: Dict[str, Any], config_name: str = "Configuration") -> T:
+        """
+        Load configuration from a dictionary strictly.
+        """
+        validator = StrictConfigValidator()
+        # This will raise an AmshaConfigurationException if it fails
+        validated_model = validator.validate_strictly(model_class, data, config_name)
+        
+        # Optionally log auditor traces
+        import logging
+        logger = logging.getLogger(__name__)
+        for log_entry in validator.audit_log:
+             logger.debug(log_entry)
+             
+        return validated_model
+
+    @staticmethod
+    def load_from_json(model_class: Type[T], path: Union[str, Path], config_name: str = "Configuration") -> T:
+        """Load configuration from a JSON file strictly."""
+        path = Path(path)
+        if not path.exists():
+            raise AmshaConfigurationException(f"Configuration file not found: {path}")
+            
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        return ConfigurationManager.load_from_dict(model_class, data, config_name)
+
+    @staticmethod
+    def load_from_yaml(model_class: Type[T], path: Union[str, Path], config_name: str = "Configuration") -> T:
+        """Load configuration from a YAML file strictly."""
+        path = Path(path)
+        if not path.exists():
+            raise AmshaConfigurationException(f"Configuration file not found: {path}")
+            
+        with open(path, 'r', encoding='utf-8') as f:
+            data = yaml.safe_load(f)
+            
+        return ConfigurationManager.load_from_dict(model_class, data, config_name)

amsha/configuration/domain/models/amsha_app_config.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+class AmshaAppConfig(BaseModel):
+    """
+    Main Application Configuration for Amsha.
+    Requires strict validation with no silent default fallbacks for critical paths.
+    """
+    domain_root_path: str = Field(..., description="Root path for domain configurations (e.g., crew_configs)")
+    output_dir_path: str = Field(..., description="Path to output directory")

amsha/configuration/domain/models/amsha_job_config.py

@@ -0,0 +1,35 @@
+from typing import List, Dict, Union, Any, Optional
+from pydantic import BaseModel, Field
+
+class CrewStep(BaseModel):
+    task_key: str = Field(..., description="Task reference key")
+    agent_key: str = Field(..., description="Agent reference key")
+
+class CrewDefinition(BaseModel):
+    steps: List[CrewStep] = Field(..., description="List of steps executed by the crew")
+    knowledge_sources: Optional[List[str]] = Field(None, description="List of knowledge source paths")
+    input: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = Field(None, description="Input definitions for the crew")
+    memory: bool = Field(
+        False,
+        description="Whether the crew uses CrewAI's unified memory",
+    )
+    checkpoint: Optional[Union[bool, Dict[str, Any]]] = Field(
+        None,
+        description=(
+            "Checkpoint configuration: a bool to enable/disable CrewAI checkpointing, "
+            "or a dict with keys enabled/on_events/provider/location/max_checkpoints."
+        ),
+    )
+
+class AmshaJobConfig(BaseModel):
+    """
+    Job Orchestration Configuration.
+    Requires explicit validation of all structured job definitions.
+    """
+    crew_name: str = Field(..., description="Name of the overall crew execution job")
+    usecase: str = Field(..., description="Usecase context for execution")
+    module_name: str = Field(..., description="Module name for categorization")
+    output_filepath: str = Field(..., description="File path indicating where final output is saved")
+    
+    crews: Dict[str, CrewDefinition] = Field(..., description="Dictionary mapping crew identifiers to their definitions")
+    pipeline: List[str] = Field(..., description="Ordered list of crews defining execution sequence")

amsha/configuration/domain/models/amsha_llm_config.py

@@ -0,0 +1,38 @@
+from typing import Dict, List, Any, Optional
+from pydantic import BaseModel, Field
+
+class LLMModelDefinition(BaseModel):
+    base_url: Optional[str] = Field(default=None, description="Base URL of the LLM API endpoint")
+    model: str = Field(..., description="Model identifier string")
+    api_key: Optional[str] = Field(default=None, description="API key")
+    api_key_env: Optional[str] = Field(default=None, description="Environment variable name for the API key")
+    api_version: Optional[str] = Field(default=None, description="API version string")
+    output_config: Optional[Dict[str, Any]] = Field(default=None, description="Output file naming and organization configuration")
+
+class LLMTypeSection(BaseModel):
+    default: str = Field(..., description="The default model key to use for this type")
+    models: Dict[str, LLMModelDefinition] = Field(..., description="Dictionary of available models by key")
+
+class LLMConfigSection(BaseModel):
+    creative: LLMTypeSection = Field(..., description="Creative LLM configurations")
+    evaluation: LLMTypeSection = Field(..., description="Evaluation LLM configurations")
+
+class LLMParametersTypeSection(BaseModel):
+    temperature: float = Field(..., description="Model temperature")
+    top_p: float = Field(..., description="Top P sampling parameter")
+    max_completion_tokens: Optional[int] = Field(default=None, description="Maximum completion tokens")
+    presence_penalty: Optional[float] = Field(default=None, description="Presence penalty parameter")
+    frequency_penalty: Optional[float] = Field(default=None, description="Frequency penalty parameter")
+    stop: Optional[List[str]] = Field(default=None, description="Stop sequences")
+
+class LLMParametersSection(BaseModel):
+    creative: LLMParametersTypeSection = Field(..., description="Parameters for creative models")
+    evaluation: LLMParametersTypeSection = Field(..., description="Parameters for evaluation models")
+
+class AmshaLLMConfig(BaseModel):
+    """
+    LLM API and Parameters Configuration.
+    Strictly validates connections and parameters without silent defaults.
+    """
+    llm: LLMConfigSection = Field(..., description="Configured LLM connections by type")
+    llm_parameters: LLMParametersSection = Field(..., description="Configured LLM hyper-parameters by type")

amsha/configuration/exceptions/amsha_configuration_exception.py

@@ -0,0 +1,16 @@
+class AmshaException(Exception):
+    """Base exception for all Amsha errors"""
+    pass
+
+class AmshaConfigurationException(AmshaException):
+    """Specific strict configuration validation error"""
+    def __init__(self, message: str, errors: list[str] = None):
+        super().__init__(message)
+        self.errors = errors or []
+        
+    def __str__(self):
+        base_msg = super().__str__()
+        if self.errors:
+            error_details = "\n".join(f" - {err}" for err in self.errors)
+            return f"{base_msg}\nValidation Errors:\n{error_details}"
+        return base_msg

amsha/configuration/infrastructure/strict_validator.py

@@ -0,0 +1,50 @@
+import logging
+from typing import Type, Any, Dict, List
+from pydantic import BaseModel, ValidationError
+
+from amsha.configuration.exceptions.amsha_configuration_exception import AmshaConfigurationException
+
+logger = logging.getLogger(__name__)
+
+class StrictConfigValidator:
+    """
+    Validator that checks input data against a Pydantic model.
+    Unlike RobustConfigValidator, this validator strictly enforces 
+    that all required fields are present and valid. Any failure 
+    will accumulate errors and raise an AmshaConfigurationException
+    to terminate execution early and prevent silent crashes.
+    """
+    def __init__(self):
+        self.audit_log: List[str] = []
+
+    def validate_strictly(self, model_class: Type[BaseModel], input_data: Dict[str, Any], config_name: str = "Configuration") -> BaseModel:
+        """
+        Validates input_data against model_class.
+        Raises AmshaConfigurationException if any validation fails.
+        """
+        if input_data is None:
+             raise AmshaConfigurationException(f"{config_name} cannot be empty or None.")
+             
+        if not isinstance(input_data, dict):
+             raise AmshaConfigurationException(f"Expected dictionary for {config_name}, got {type(input_data).__name__}.")
+
+        try:
+            # Pydantic will perform strict validation based on the model.
+            # Missing fields configured with `Field(...)` will throw ValidationErrors.
+            validated_model = model_class(**input_data)
+            self.audit_log.append(f"[VALID] {config_name} passed strict validation.")
+            return validated_model
+            
+        except ValidationError as e:
+            # Extract detailed errors from Pydantic
+            detailed_errors = []
+            for err in e.errors():
+                loc = ".".join([str(x) for x in err.get("loc", [])])
+                msg = err.get("msg", "")
+                detailed_errors.append(f"Field '{loc}': {msg}")
+            
+            error_msg = f"❌ Strict Validation Failed for {config_name}."
+            logger.error(error_msg)
+            
+            # Immediately raise our custom exception with the accumulated details
+            raise AmshaConfigurationException(error_msg, errors=detailed_errors) from e

amsha/crew_forge/__init__.py

@@ -0,0 +1,4 @@
+from .orchestrator.file.amsha_crew_file_application import AmshaCrewFileApplication
+from .orchestrator.flow.flow_crew_pipeline import FlowCrewOrchestrator, PipelineState
+
+__all__ = ["AmshaCrewFileApplication", "FlowCrewOrchestrator", "PipelineState"]

amsha/crew_forge/domain/models/agent_data.py

@@ -0,0 +1,34 @@
+# src/nikhil/amsha/toolkit/crew_forge/domain/agent_data.py
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from amsha.crew_forge.domain.models.mcp_data import McpServerConfig
+
+
+class AgentRequest(BaseModel):
+    role: str = Field(..., description="The role or persona of the agent.")
+    goal: str = Field(..., description="The primary objective or goal of the agent.")
+    backstory: str = Field(..., description="The backstory or context for the agent.")
+    usecase: Optional[str] = Field(None, description="The Usecase or context for the agent for its use")
+
+    # Execution tuning
+    max_iter: Optional[int] = Field(None, description="Maximum number of iterations for the agent.")
+    max_rpm: Optional[int] = Field(None, description="Maximum requests per minute.")
+    max_execution_time: Optional[int] = Field(None, description="Maximum execution time (seconds).")
+    max_retry_limit: Optional[int] = Field(None, description="Maximum number of retries on tool failure.")
+    respect_context_window: Optional[bool] = Field(None, description="Respect the context window when sending messages.")
+    allow_delegation: Optional[bool] = Field(None, description="Allow the agent to delegate tasks to other agents.")
+
+    # Capabilities
+    reasoning: Optional[bool] = Field(None, description="Enable reasoning model.")
+    max_reasoning_attempts: Optional[int] = Field(None, description="Maximum reasoning attempts when reasoning is enabled.")
+    multimodal: Optional[bool] = Field(None, description="Enable multimodal (image/audio) inputs.")
+    skills: Optional[List[str]] = Field(None, description="Skill names or paths to attach to the agent.")
+    tools: Optional[List[str]] = Field(None, description="Tool names resolved against the tool registry.")
+    mcp_servers: Optional[List[McpServerConfig]] = Field(None, description="MCP server configurations for this agent.")
+
+    # Prompt customization
+    system_template: Optional[str] = Field(None, description="System template override.")
+    prompt_template: Optional[str] = Field(None, description="Prompt template override.")
+    response_template: Optional[str] = Field(None, description="Response template override.")

amsha/crew_forge/domain/models/crew_data.py

@@ -0,0 +1,30 @@
+# src/nikhil/amsha/toolkit/crew_forge/domain/crew_data.py
+from typing import Any, Dict, Optional, Union
+
+from crewai.llms.base_llm import BaseLLM
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class CrewData(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    llm: BaseLLM = Field(..., description="Model name")
+    module_name: str = Field(..., description="The name of module")
+    output_dir_path: Optional[str] = Field(..., description="output dir path")
+    memory: bool = Field(
+        default=False,
+        description="Whether the crew uses CrewAI's unified memory",
+    )
+    checkpoint: Optional[Union[bool, Dict[str, Any]]] = Field(
+        default=None,
+        description=(
+            "Checkpoint configuration: a bool to enable/disable CrewAI checkpointing, "
+            "or a dict with keys enabled/on_events/provider/location/max_checkpoints."
+        ),
+    )
+    tracing: Optional[bool] = Field(
+        default=None,
+        description=(
+            "Enable CrewAI native tracing (sends full prompt/response content "
+            "to CrewAI's hosted dashboard). Off by default — requires crewai login."
+        ),
+    )

amsha/crew_forge/domain/models/mcp_data.py

@@ -0,0 +1,49 @@
+# src/nikhil/amsha/crew_forge/domain/models/mcp_data.py
+"""MCP server configuration models for YAML config-as-code.
+
+These models constrain what's expressible in YAML — no raw dict passthrough.
+"""
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class McpServerConfig(BaseModel):
+    """Structured MCP server configuration — Amsha's YAML-facing schema.
+
+    ``transport`` discriminates which fields are relevant:
+    - ``stdio``: ``command`` + ``args`` + ``env``
+    - ``http`` / ``sse``: ``url`` + ``headers``
+    """
+
+    transport: Literal["stdio", "http", "sse"] = Field(
+        ...,
+        description="MCP transport type.",
+    )
+    # stdio fields
+    command: Optional[str] = Field(
+        None,
+        description="Command to execute for stdio transport (e.g. 'python', 'node').",
+    )
+    args: Optional[List[str]] = Field(
+        None,
+        description="Command arguments for stdio transport.",
+    )
+    env: Optional[Dict[str, str]] = Field(
+        None,
+        description="Environment variables for stdio transport (replaces parent env).",
+    )
+    # http / sse fields
+    url: Optional[str] = Field(
+        None,
+        description="Server URL for http/sse transport.",
+    )
+    headers: Optional[Dict[str, str]] = Field(
+        None,
+        description="HTTP headers for http/sse transport (e.g. auth tokens).",
+    )
+    # common
+    connect_timeout: int = Field(
+        30,
+        description="Connection timeout in seconds.",
+    )

amsha/crew_forge/domain/models/task_data.py

@@ -0,0 +1,22 @@
+# src/nikhil/amsha/toolkit/crew_forge/domain/task_data.py
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TaskRequest(BaseModel):
+    name: str = Field(..., description="The name of the task.")
+    description: str = Field(..., description="Description of the task to be performed.")
+    expected_output: str = Field(..., description="The expected output or result of the task.")
+    usecase: Optional[str] = Field(None, description="The Usecase or context for the task for its use")
+
+    # Execution
+    context: Optional[List[str]] = Field(None, description="Names of prerequisite TaskRequests whose output feeds this task.")
+    tools: Optional[List[str]] = Field(None, description="Tool names resolved against the tool registry. Task-level tools override agent-level tools.")
+    async_execution: Optional[bool] = Field(None, description="Execute this task asynchronously.")
+    human_input: Optional[bool] = Field(None, description="Require human input before final output.")
+    markdown: Optional[bool] = Field(None, description="Render the task output as markdown.")
+
+    # Guardrails
+    guardrail: Optional[str] = Field(None, description="LLM-based guardrail description for validating task output.")
+    guardrail_max_retries: Optional[int] = Field(None, description="Maximum retries when the guardrail fails.")