rasa-pro 3.13.11__py3-none-any.whl → 3.14.0__py3-none-any.whl

rasa/builder/exceptions.py

@@ -0,0 +1,91 @@
+"""Custom exceptions for the prompt-to-bot service."""
+
+from typing import Any, Dict, List, Optional
+
+
+class PromptToBotError(Exception):
+    """Base exception for prompt-to-bot service."""
+
+    pass
+
+
+class ValidationError(PromptToBotError):
+    """Raised when Rasa project validation fails."""
+
+    def __init__(
+        self, message: str, validation_logs: Optional[List[Dict[str, Any]]] = None
+    ):
+        super().__init__(message)
+        self.validation_logs = validation_logs or []
+
+    def get_logs(self, log_levels: Optional[List[str]]) -> List[Dict[str, Any]]:
+        """Get logs filtered by given log levels."""
+        if len(self.validation_logs) == 0:
+            return []
+
+        error_log_entries: List[Dict[str, Any]] = []
+        for log_entry in self.validation_logs:
+            if log_levels is not None and log_entry.get("log_level") in log_levels:
+                error_log_entries.append(log_entry)
+
+        return error_log_entries
+
+    def get_error_message_with_logs(
+        self, log_levels: Optional[List[str]] = None
+    ) -> str:
+        """Get the error message with validation logs for specified log levels.
+
+        Args:
+            log_levels: List of log levels to include. If None, includes all logs.
+
+        Returns:
+            Error message with validation logs appended.
+        """
+        error_message = str(self)
+
+        # Include all logs when no specific levels are specified
+        logs = self.validation_logs if log_levels is None else self.get_logs(log_levels)
+
+        if logs:
+            logs_text = "\n".join([str(log) for log in logs])
+            error_message += f"\n\nValidation Logs:\n{logs_text}\n"
+
+        return error_message
+
+
+class TrainingError(PromptToBotError):
+    """Raised when model training fails."""
+
+    pass
+
+
+class LLMGenerationError(PromptToBotError):
+    """Raised when LLM generation fails."""
+
+    pass
+
+
+class DocumentRetrievalError(PromptToBotError):
+    """Raised when document retrieval fails."""
+
+    pass
+
+
+class SchemaValidationError(PromptToBotError):
+    """Raised when schema validation fails."""
+
+    pass
+
+
+class AgentLoadError(PromptToBotError):
+    """Raised when agent loading fails."""
+
+    pass
+
+
+class ProjectGenerationError(PromptToBotError):
+    """Raised when project generation fails after retries."""
+
+    def __init__(self, message: str, attempts: int):
+        super().__init__(f"{message} (failed after {attempts} attempts)")
+        self.attempts = attempts

rasa/builder/guardrails/__init__.py

@@ -0,0 +1 @@
+

rasa/builder/guardrails/clients.py

@@ -0,0 +1,256 @@
+"""Guardrails client implementations."""
+
+import asyncio
+import os
+import time
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager
+from functools import lru_cache
+from typing import Any, AsyncGenerator, Dict, Optional
+
+import aiohttp
+import structlog
+
+from rasa.builder import config
+from rasa.builder.guardrails.constants import (
+    LAKERA_API_KEY_ENV_VAR,
+    LAKERA_GUARD_ENDPOINT,
+    LAKERA_GUARD_RESULTS_ENDPOINT,
+)
+from rasa.builder.guardrails.exceptions import GuardrailsError
+from rasa.builder.guardrails.models import (
+    GuardrailRequest,
+    GuardrailResponse,
+    LakeraGuardrailRequest,
+    LakeraGuardrailResponse,
+)
+
+structlogger = structlog.get_logger()
+
+
+class GuardrailsClient(ABC):
+    """Abstract base class for guardrails clients."""
+
+    @property
+    @abstractmethod
+    def guard_endpoint(self) -> str:
+        """Get the guard endpoint for the guardrails API."""
+        pass
+
+    @abstractmethod
+    async def send_request(self, request: GuardrailRequest) -> GuardrailResponse:
+        """Send a request to the guardrails provider.
+
+        Args:
+            request: The guardrail request to send to the provider.
+
+        Returns:
+            GuardrailResponse with the results of the check.
+
+        Raises:
+            GuardrailsError: If the request fails for any reason.
+        """
+        pass
+
+    @lru_cache(maxsize=512)
+    def schedule_check(
+        self,
+        request: GuardrailRequest,
+    ) -> "asyncio.Task[GuardrailResponse]":
+        """Return a cached asyncio.Task that resolves to guardrail response.
+
+        Args:
+            request: The guardrail request to send to the provider.
+
+        Returns:
+            An asyncio Task that resolves to a GuardrailResponse.
+        """
+        structlogger.debug(
+            "guardrails.schedule_check.cache_miss",
+            request=request.model_dump(),
+        )
+        loop = asyncio.get_running_loop()
+        return loop.create_task(self.send_request(request))
+
+
+class LakeraAIGuardrails(GuardrailsClient):
+    """Guardrails provider using Lakera AI."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ):
+        """Initialize Lakera guardrails provider.
+
+        Args:
+            api_key: Lakera AI API key.
+            base_url: Optional base URL for the API. If not provided, the default
+                Lakera API URL (https://api.lakera.ai/v2) will be used.
+        """
+        self.base_url: str = base_url or config.LAKERA_BASE_URL
+        self._api_key: Optional[str] = api_key or os.getenv(LAKERA_API_KEY_ENV_VAR)
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    @property
+    def guard_endpoint(self) -> str:
+        """Get the guard endpoint for the Lakera API."""
+        return f"{self.base_url}/{LAKERA_GUARD_ENDPOINT}"
+
+    @property
+    def guard_results_endpoint(self) -> str:
+        """Get the guard results endpoint for the Lakera API."""
+        return f"{self.base_url}/{LAKERA_GUARD_RESULTS_ENDPOINT}"
+
+    @asynccontextmanager
+    async def _get_session(self) -> AsyncGenerator[aiohttp.ClientSession, None]:
+        """Create a fresh ClientSession, yield it, and always close it."""
+        session = aiohttp.ClientSession(headers=self._get_headers())
+        structlogger.debug("lakera_guardrails._get_session", base_url=self.base_url)
+
+        try:
+            yield session
+        except Exception as e:
+            structlogger.error("lakera_guardrails.session_error", error=str(e))
+            raise
+        finally:
+            try:
+                await session.close()
+            except Exception as exc:
+                structlogger.warning(
+                    "lakera_guardrails.session_close_error",
+                    event_info="Failed to close aiohttp client session cleanly.",
+                    error=str(exc),
+                )
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get the headers for the Lakera API request.
+
+        Returns:
+            A dictionary containing the Authorization header with the API key.
+        """
+        using_proxy = bool(config.HELLO_LLM_PROXY_BASE_URL)
+
+        if using_proxy:
+            if not config.RASA_PRO_LICENSE:
+                raise GuardrailsError(
+                    "HELLO_LLM_PROXY_BASE_URL is set but RASA_PRO_LICENSE is missing. "
+                    "Proxy requires a Rasa Pro license token for authentication."
+                )
+            return {"Authorization": f"Bearer {config.RASA_PRO_LICENSE}"}
+
+        if not self._api_key:
+            raise GuardrailsError(
+                "LAKERA_API_KEY is missing. Provide it via env LAKERA_API_KEY or "
+                "pass api_key= to LakeraAIGuardrails."
+            )
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    async def send_request(self, request: GuardrailRequest) -> GuardrailResponse:
+        """Send a request to the Lakera API.
+
+        Args:
+            request: The guardrail request to send to the Lakera API.
+
+        Returns:
+            GuardrailResponse with the results of the check.
+
+        Raises:
+            GuardrailsError: If the request times out or returns a non-200 status code.
+            Exception: If the request fails for any other reason.
+        """
+        if not isinstance(request, LakeraGuardrailRequest):
+            raise GuardrailsError(
+                "LakeraAIGuardrails only supports LakeraGuardrailRequest"
+            )
+        start_time = time.time()
+        try:
+            async with self._get_session() as session:
+                raw_response = await self._send_http_request(session, request)
+                response = LakeraGuardrailResponse.from_raw_response(
+                    raw_response,
+                    hello_rasa_user_id=request.hello_rasa_user_id,
+                    hello_rasa_project_id=request.hello_rasa_project_id,
+                )
+                processing_time_ms = (time.time() - start_time) * 1000
+                response.processing_time_ms = processing_time_ms
+                return response
+
+        # Propagate the GuardrailsError if it occurs.
+        except GuardrailsError as e:
+            raise e
+
+        except asyncio.TimeoutError:
+            message = "Lakera API request timed out."
+            structlogger.error(
+                "lakera_guardrails.send_request.timeout_error",
+                event_info=message,
+                processing_time_ms=(time.time() - start_time) * 1000,
+            )
+            raise GuardrailsError(message)
+
+        # Propagate the unexpected exceptions.
+        except Exception as e:
+            message = "Lakera API request failed."
+            structlogger.error(
+                "lakera_guardrails.send_request.unexpected_error",
+                event_info="Lakera API request failed.",
+                request=request,
+                error=e,
+                processing_time_ms=(time.time() - start_time) * 1000,
+            )
+            raise e
+
+    async def _send_http_request(
+        self, session: aiohttp.ClientSession, request: LakeraGuardrailRequest
+    ) -> Dict[str, Any]:
+        """Make an HTTP request to the Lakera API.
+
+        Args:
+            session: The aiohttp session to use for the request.
+            request: The guardrail request to send.
+
+        Returns:
+            The raw JSON response from the API.
+
+        Raises:
+            GuardrailsError: If the request fails or response parsing fails.
+        """
+        # Log the request details for debugging
+        json_payload = request.to_json_payload()
+        structlogger.debug(
+            "lakera_guardrails.send_request.request",
+            url=self.guard_endpoint,
+            method="POST",
+            request_body=json_payload,
+        )
+
+        async with session.post(
+            self.guard_endpoint,
+            json=json_payload,
+        ) as client_response:
+            # Check if the response is successful. If not, raise an error.
+            if client_response.status >= 400:
+                error_text = await client_response.text()
+                message = (
+                    f"Lakera API request failed with status "
+                    f"`{client_response.status}`. Error: "
+                    f"`{error_text}`."
+                )
+                structlogger.error(
+                    "lakera_guardrails.send_request.http_error",
+                    event_info=message,
+                    url=self.guard_endpoint,
+                    status=client_response.status,
+                    error=error_text,
+                    request_body=json_payload,
+                )
+                raise GuardrailsError(message)
+
+            # Parse the response as a dictionary.
+            raw_response = await client_response.json()
+            structlogger.debug(
+                "lakera_guardrails.send_request.response",
+                response_body=raw_response,
+            )
+            return raw_response

rasa/builder/guardrails/constants.py

@@ -0,0 +1,12 @@
+from typing import Literal
+
+LAKERA_API_KEY_ENV_VAR = "LAKERA_API_KEY"
+LAKERA_GUARD_ENDPOINT = "guard"
+LAKERA_GUARD_RESULTS_ENDPOINT = "guard/results"
+
+# Metadata keys for GuardrailRequestKey
+LAKERA_PROJECT_ID_KEY = "lakera_project_id"
+
+BLOCK_SCOPE_USER: Literal["user"] = "user"
+BLOCK_SCOPE_PROJECT: Literal["project"] = "project"
+BlockScope = Literal["user", "project"]

rasa/builder/guardrails/exceptions.py

@@ -0,0 +1,4 @@
+class GuardrailsError(Exception):
+    """Raised when a guardrails error occurs."""
+
+    pass

rasa/builder/guardrails/models.py

@@ -0,0 +1,266 @@
+"""Models for guardrails system."""
+
+import copy
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class GuardrailType(Enum):
+    """Types of guardrails that can be applied with Lakera AI."""
+
+    PROMPT_ATTACK = "prompt_attack"
+    CONTENT_VIOLATION = "content_violation"
+    DATA_LEAKAGE = "data_leakage"
+    MALICIOUS_LINKS = "malicious_content"
+    CUSTOM = "custom"
+    OTHER = "other"
+
+
+class GuardrailRequestKey(BaseModel):
+    user_text: str
+    hello_rasa_user_id: str = ""
+    hello_rasa_project_id: str = ""
+    # Generic metadata field for provider-specific configurations
+    metadata: Dict[str, str] = Field(default_factory=dict)
+
+    # hashable by value
+    model_config = ConfigDict(frozen=True)
+
+    def __hash__(self) -> int:
+        """Custom hash implementation that handles the metadata dictionary."""
+        # Convert metadata dict to a sorted tuple of items for consistent hashing
+        metadata_tuple = tuple(sorted(self.metadata.items())) if self.metadata else ()
+        hash_tuple = (
+            self.user_text,
+            self.hello_rasa_user_id,
+            self.hello_rasa_project_id,
+            tuple(sorted(metadata_tuple)),
+        )
+        return hash(hash_tuple)
+
+
+class GuardrailRequest(BaseModel, ABC):
+    """Request for guardrails check."""
+
+    hello_rasa_user_id: Optional[str] = Field(
+        default=None,
+        description="Required. User identifier for the Hello Rasa project. ",
+    )
+    hello_rasa_project_id: Optional[str] = Field(
+        default=None,
+        description="Required. Project identifier for the Hello Rasa project. ",
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None, description="Additional metadata for the guardrails endpoint."
+    )
+
+    @abstractmethod
+    def to_json_payload(self) -> Dict[str, Any]:
+        """Convert the request to a JSON payload."""
+        ...
+
+
+class LakeraGuardrailRequest(GuardrailRequest):
+    """Request for Lakera guardrails check."""
+
+    lakera_project_id: str = Field(
+        description="Required. Project identifier for the Lakera AI project."
+    )
+    payload: bool = Field(
+        default=True,
+        description=(
+            "From Lakera AI: When true the response will return a payload object "
+            "containing any PII, profanity or custom detector regex matches detected, "
+            "along with their location within the contents."
+        ),
+    )
+    breakdown: bool = Field(
+        default=True,
+        description=(
+            "From Lakera AI: When true the response will return a breakdown list of "
+            "the detectors that were run, as defined in the policy, and whether each "
+            "of them detected something or not."
+        ),
+    )
+
+    messages: List[Dict[str, Any]] = Field(
+        description=(
+            "Required. From Lakera AI: List of messages comprising the interaction "
+            "history with the LLM in OpenAI API Chat Completions format. Can be "
+            "multiple messages of any role: user, assistant, system, tool, or "
+            "developer."
+        ),
+    )
+
+    # Make the model hashable by value for use as cache keys in @lru_cache decorator.
+    model_config = ConfigDict(frozen=True)
+
+    def to_json_payload(self) -> Dict[str, Any]:
+        """Convert the request to a JSON payload to be sent to the Lakera endpoint."""
+        metadata = self.metadata or {}
+        metadata["hello_rasa_project_id"] = self.hello_rasa_project_id
+        metadata["hello_rasa_user_id"] = self.hello_rasa_user_id
+
+        json_payload: Dict[str, Any] = {
+            "messages": self.messages,
+            "project_id": self.lakera_project_id,
+            "metadata": metadata,
+        }
+
+        if self.payload:
+            json_payload["payload"] = self.payload
+        if self.breakdown:
+            json_payload["breakdown"] = self.breakdown
+
+        return json_payload
+
+    def __hash__(self) -> int:
+        """Custom hash implementation that handles the messages list."""
+        # Convert messages list to a tuple for consistent hashing
+        if self.messages:
+            messages_tuple = tuple(tuple(msg.items()) for msg in self.messages)
+        else:
+            messages_tuple = ()
+
+        hash_tuple = (
+            self.hello_rasa_user_id,
+            self.hello_rasa_project_id,
+            self.lakera_project_id,
+            self.payload,
+            self.breakdown,
+            messages_tuple,
+            tuple(sorted(self.metadata.items())) if self.metadata else (),
+        )
+        return hash(hash_tuple)
+
+
+class GuardrailDetection(BaseModel):
+    """Represents a single guardrail detection."""
+
+    type: GuardrailType = Field(description="Type of guardrail detection.")
+    original_type: str = Field(description="Original detection from the provider.")
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None, description="Additional metadata about the detection itself."
+    )
+
+
+class GuardrailResponse(BaseModel):
+    """Response from guardrails system."""
+
+    hello_rasa_user_id: Optional[str] = Field(
+        default=None,
+        description="Required. User identifier for the Hello Rasa project. ",
+    )
+    hello_rasa_project_id: Optional[str] = Field(
+        default=None,
+        description="Required. Project identifier for the Hello Rasa project. ",
+    )
+    flagged: bool = Field(description="Whether any policy violations were detected.")
+    detections: List[GuardrailDetection] = Field(
+        default_factory=list, description="List of detected policy violations."
+    )
+    processing_time_ms: Optional[float] = Field(
+        default=None, description="Processing time in milliseconds."
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None, description="Additional metadata from the provider."
+    )
+
+
+class LakeraGuardrailResponse(GuardrailResponse):
+    """Response from Lakera AI `/guard` endpoint."""
+
+    @classmethod
+    def from_raw_response(
+        cls,
+        raw_response: Dict[str, Any],
+        hello_rasa_user_id: str,
+        hello_rasa_project_id: str,
+    ) -> "LakeraGuardrailResponse":
+        """Create a LakeraGuardrailResponse from a response."""
+        from rasa.builder.guardrails.utils import (
+            map_lakera_detector_type_to_guardrail_type,
+        )
+
+        # Get the basic information from the response and create the response object.
+        flagged = raw_response.get("flagged", False)
+        metadata = raw_response.get("metadata")
+        response = cls(
+            flagged=flagged,
+            metadata=metadata,
+            hello_rasa_user_id=hello_rasa_user_id,
+            hello_rasa_project_id=hello_rasa_project_id,
+        )
+
+        # If the response is not flagged, return the response object.
+        if not flagged:
+            return response
+
+        # If the response is flagged, parse the breakdown section.
+        breakdown = raw_response.get("breakdown", [])
+
+        # Parse the breakdown.
+        detections: List[GuardrailDetection] = []
+        for detector in breakdown:
+            if detector.get("detected", True):
+                detector_type = detector.get("detector_type")
+                rasa_detection_type = map_lakera_detector_type_to_guardrail_type(
+                    detector_type,
+                )
+                if not rasa_detection_type:
+                    continue
+                # Remove the detector type and the detected flag from the detector.
+                # And keep the rest as part of the metadata. In case of a Lakera this
+                # will include the message_id, project_id, policy_id, detector_id, etc.
+                metadata = copy.deepcopy(detector)
+                metadata.pop("detected")
+                metadata.pop("detector_type")
+
+                detections.append(
+                    GuardrailDetection(
+                        type=rasa_detection_type,
+                        original_type=detector_type,
+                        metadata=metadata,
+                    )
+                )
+
+        # If there are detections, add them to the response.
+        if detections:
+            response.detections = detections
+
+        return response
+
+
+class ScopeState(BaseModel):
+    blocked_until: Optional[float] = Field(
+        default=None,
+        description="UNIX timestamp in seconds until this scope is blocked.",
+    )
+    violations: List[float] = Field(
+        default_factory=list,
+        description="UNIX timestamps in seconds when violations occurred.",
+    )
+
+    def is_blocked(self, now: float) -> bool:
+        """Return whether the scope is currently blocked.
+
+        Args:
+            now: Current time as a UNIX timestamp.
+
+        Returns:
+            True if blocked_until is set and in the future, else False.
+        """
+        return self.blocked_until is not None and now < self.blocked_until
+
+
+class ProjectState(BaseModel):
+    project: ScopeState = Field(default_factory=ScopeState)
+    users: Dict[str, ScopeState] = Field(default_factory=dict)
+
+
+class BlockResult(BaseModel):
+    user_blocked_now: bool = False
+    project_blocked_now: bool = False