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

rasa/builder/copilot/prompts/copilot_training_error_handler_prompt.jinja2

@@ -0,0 +1,53 @@
+# Task
+Your task is to help the user fix a training error that occurred when they clicked the
+"Apply Changes" button. The user made changes to their assistant project files and tried
+to apply them, but the training process failed. You must always explain the error within
+the context of the user's **assistant project files** (flows, domain, actions, config).
+
+---
+
+# Response guidelines
+
+1. **Summary** - Start with one short sentence that explains what happened in plain language.
+2. **Explanation** - Describe why this error occurs in Rasa Assistant, focusing only on
+   assistant project files. Be precise but simple. Do not speculate or reference Rasa
+   internals unrelated to project files.
+3. **Fix Steps** - Provide clear, numbered instructions.
+   - Point to specific files (`flows.yml`, `domain.yml`, `actions.py`, etc.).
+   - Include corrected YAML or Python snippets if needed.
+   - Validate syntax and indentation.
+   - Reference documentation for configuration options, syntax rules, or best practices.
+4. **Validation** - End with one line suggesting how to re-test
+5. **Multiple Errors** - If multiple error logs are present, you **must** address and
+   propose fixes for **all of them**, not just one.
+
+# Context
+
+## Relevant Documentation
+
+{% if documentation_results %}
+The following documentation sources are available for reference. Use the source index
+numbers (1, 2, 3, etc.) for inline citations when explaining Rasa concepts or providing
+authoritative fixes:
+```
+{{ documentation_results }}
+```
+{% else %}
+No relevant documentation source found.
+{% endif %}
+
+## Modified assistant project files
+
+{% if modified_files %}
+{{ modified_files }}
+{% else %}
+No modified assistant project files.
+{% endif %}
+
+## Available assistant logs
+
+{% if logs %}
+{{ logs }}
+{% else %}
+No assistant logs available.
+{% endif %}

rasa/builder/copilot/prompts/latest_user_message_context_prompt.jinja2

@@ -0,0 +1,91 @@
+# Context Priority
+When interpreting user questions (especially vague ones like *"What's this?"*), follow
+this order of priority:
+
+| Priority | Context Source | Usage |
+|----------|----------------|-------|
+| 1 | **Attachments** | Highest priority. If attachments exist, assume the user's question refers to them. Always ground explanations in attachment content first. |
+| 2 | **Assistant State / Current Conversation** | Use this when attachments are not present. Supplement attachment knowledge with state info if needed. |
+| 3 | **Assistant Files** | Use when neither attachments nor state provide enough context. |
+| 4 | **Documentation Results** | Use to explain Rasa features and validate facts. Must always be cited inline. |
+| 5 | **Assistant Logs** | Lowest priority. Use only if directly relevant to the user’s issue. |
+
+---
+
+# Remember!
+- Focus on accessibility and efficiency. Give guidance users can act on right away.
+- Keep answers concise, cut any fluff.
+- Never impersonate or role-play as the assistant being built. You are the **Rasa assistant development expert**.
+- Cite documentation inline frequently — every factual statement about Rasa features, concepts, or capabilities MUST be cited.
+- Only cite from current turn documentation — never from previous conversation turns.
+- NEVER add a separate list of URLs or sources — only use inline citations.
+- NEVER start your response with a ``` or """ or any other quoting characters.
+
+---
+
+# Context Available to You
+Treat everything **below** as context for the user's current request.  
+You have access to:
+
+***
+
+## Assistant Files (Configuration, Domain, Flows)
+{% if assistant_files %}
+{% for file_name, file_content in assistant_files.items() %}
+**{{ file_name }}:**
+```
+{{ file_content }}
+```
+{% endfor %}
+{% else %}
+Assistant files are not available.
+{% endif %}
+
+***
+
+## Relevant Documentation
+{% if documentation_results %}
+The following documentation sources are available for reference. Use the source index
+numbers (1, 2, 3, etc.) for inline citations:
+```
+{{documentation_results}}
+```
+{% else %}
+No relevant documentation source found.
+{% endif %}
+
+{% if current_conversation %}
+***
+
+## Current Conversation and Conversation State between the user and the assistant
+
+**Conversation History:**
+```json
+{{ current_conversation }}
+```
+
+**Assistant's State:**
+```json
+{{ current_state }}
+```
+{% endif %}
+
+{% if assistant_logs %}
+***
+
+## Assistant Logs
+```
+{{ assistant_logs }}
+```
+{% endif %}
+
+{% if attachments %}
+***
+
+## Attachments
+The user clicked **Ask Copilot** in the **Inspect Mode** and included additional context
+as attachments:
+```json
+{{ attachments }}
+```
+{% endif %}

rasa/builder/copilot/signing.py

@@ -0,0 +1,305 @@
+import base64
+import hashlib
+import hmac
+import json
+from typing import Any, List, Optional, Tuple
+
+import structlog
+
+from rasa.builder import config
+from rasa.builder.copilot.constants import ROLE_COPILOT, ROLE_USER, SIGNATURE_VERSION_V1
+from rasa.builder.copilot.copilot_response_handler import CopilotResponseHandler
+from rasa.builder.copilot.exceptions import (
+    InvalidCopilotChatHistorySignature,
+    MissingCopilotChatHistorySignature,
+)
+from rasa.builder.copilot.models import (
+    CopilotChatMessage,
+    CopilotRequest,
+    GeneratedContent,
+    ResponseCategory,
+    ResponseCompleteness,
+    ServerSentEvent,
+    SigningContext,
+    TextContent,
+)
+
+structlogger = structlog.get_logger()
+
+
+def _b64url_no_pad(bytes_to_convert: bytes) -> str:
+    """Convert bytes to a base64 URL-safe string without padding.
+
+    Args:
+        bytes_to_convert: Bytes to convert.
+
+    Returns:
+        str: Base64 URL-safe encoded string without padding.
+    """
+    return base64.urlsafe_b64encode(bytes_to_convert).rstrip(b"=").decode("ascii")
+
+
+def _canonicalize_messages(messages: List[CopilotChatMessage]) -> bytes:
+    """Canonicalize messages to a deterministic JSON format suitable for signing.
+
+    Args:
+        messages: List of CopilotChatMessage objects to normalize.
+
+    Returns:
+        bytes: Canonicalized JSON string of messages.
+    """
+    canonical: List[dict] = []
+
+    for message in messages:
+        # Preserve internal roles exactly as sent by the client (e.g. "user",
+        # "copilot", or any future internal roles) and keep structured content blocks.
+        message_dict = message.model_dump(
+            include={"role", "content"}, exclude_none=True
+        )
+
+        role = message_dict.get("role", "")
+        content = message_dict.get("content", [])
+
+        canonical.append({"role": role, "content": content})
+
+    # Dump to JSON with consistent formatting
+    return json.dumps(
+        canonical,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+def compute_history_signature(
+    messages: List[CopilotChatMessage],
+    session_id: str,
+    secret: str,
+    version: str = SIGNATURE_VERSION_V1,
+) -> str:
+    """Compute a signature for the chat history messages.
+
+    Args:
+        messages: List of CopilotChatMessage objects representing the chat history.
+        session_id: Unique identifier for the session.
+        secret: Secret key used for signing.
+        version: Version of the signature format (default is SIGNATURE_VERSION_V1).
+
+    Returns:
+        str: Base64 URL-safe encoded signature.
+    """
+    canonical = _canonicalize_messages(messages)
+    mac_input = (
+        version.encode("utf-8")
+        + b"\x00"
+        + session_id.encode("utf-8")
+        + b"\x00"
+        + canonical
+    )
+    digest = hmac.new(
+        key=secret.encode("utf-8"), msg=mac_input, digestmod=hashlib.sha256
+    ).digest()
+    signature = _b64url_no_pad(digest)
+    return signature
+
+
+def verify_history_signature(
+    history_signature: str,
+    messages: List[CopilotChatMessage],
+    session_id: str,
+    secret: str,
+    version: Optional[str],
+) -> bool:
+    """Verify the history signature against the provided messages and session ID.
+
+    Args:
+        history_signature: Base64 URL-safe encoded signature to verify.
+        messages: List of CopilotChatMessage objects representing the chat history.
+        session_id: Unique identifier for the session.
+        secret: Secret key used for signing.
+        version: Version of the signature format (default is SIGNATURE_VERSION_V1).
+
+    Returns:
+        bool: True if the signature is valid, False otherwise.
+    """
+    version = version or SIGNATURE_VERSION_V1
+    expected_signature = compute_history_signature(
+        messages=messages, session_id=session_id, secret=secret, version=version
+    )
+    return hmac.compare_digest(expected_signature, history_signature)
+
+
+def _signing_context() -> Optional[SigningContext]:
+    """Get the signing context for history signatures.
+
+    Returns:
+        SigningContext if a secret is present, otherwise None.
+    """
+    if not (secret := config.COPILOT_HISTORY_SIGNING_SECRET):
+        return None
+
+    return SigningContext(
+        secret=secret,
+        default_version=SIGNATURE_VERSION_V1,
+    )
+
+
+async def verify_signature(req: CopilotRequest) -> bool:
+    """Verify the history signature for a request.
+
+    Args:
+        req: Request object containing copilot chat history and session ID.
+
+    Returns:
+        True if verification passes.
+
+    Raises:
+        InvalidCopilotChatHistorySignature: when the provided signature doesn't match.
+        MissingCopilotChatHistorySignature: when a required signature is missing.
+    """
+    context = _signing_context()
+
+    # If no server-side secret, signature verification is not enforced
+    if context is None:
+        return True
+
+    # If the client didn't opt in by providing the signature version, skip verification
+    if not (signature_version := getattr(req, "signature_version", None)):
+        return True
+
+    # Allow missing signature on first user turn
+    user_message_count = sum(
+        1 for m in req.copilot_chat_history if getattr(m, "role", None) == ROLE_USER
+    )
+    allow_missing = user_message_count <= 1
+    version = signature_version or context.default_version
+
+    history_signature = getattr(req, "history_signature", None)
+    if history_signature and context.secret:
+        # We generate the signature against the conversation history,
+        # excluding the user message if it's the last one in the list
+        messages = req.copilot_chat_history
+        if user_message_count and req.copilot_chat_history[-1].role == ROLE_USER:
+            messages = req.copilot_chat_history[:-1]
+
+        is_valid = verify_history_signature(
+            history_signature=history_signature,
+            messages=messages,
+            session_id=req.session_id,
+            secret=context.secret,
+            version=version,
+        )
+        if not is_valid:
+            structlogger.error(
+                "copilot.signing.invalid_history_signature",
+                version=version,
+                session_id=req.session_id,
+            )
+            raise InvalidCopilotChatHistorySignature("invalid_history_signature")
+        return True
+
+    # Client opted in and this is not the first turn → signature is required
+    if not allow_missing:
+        structlogger.error(
+            "copilot.signing.missing_history_signature",
+            version=version,
+            session_id=req.session_id,
+        )
+        raise MissingCopilotChatHistorySignature("missing_history_signature")
+
+    # Soft mode for first turn without signature
+    return True
+
+
+async def create_signature_envelope_for_text(
+    req: CopilotRequest,
+    text: str,
+    category: ResponseCategory,
+) -> Optional[ServerSentEvent]:
+    """Create a signature SSE envelope for the assistant message.
+
+    Args:
+        req: Request object containing copilot chat history and session ID.
+        text: Text content of the assistant message.
+        category: Response category of the assistant message.
+
+    Returns:
+        Optional[ServerSentEvent]: SSE envelope with signature data or None if
+        signing is not applicable.
+    """
+    context = _signing_context()
+
+    # If no server-side secret, signature verification is not enforced
+    if context is None:
+        return None
+
+    if not getattr(req, "signature_version", None):
+        return None
+
+    assistant_message = CopilotChatMessage(
+        role=ROLE_COPILOT,
+        content=[TextContent(type="text", text=text)],
+        response_category=category,
+    )
+    next_history = [*req.copilot_chat_history, assistant_message]
+    version = getattr(req, "signature_version", None) or context.default_version
+    signature = compute_history_signature(
+        messages=next_history,
+        session_id=req.session_id,
+        secret=context.secret,
+        version=version,
+    )
+
+    return ServerSentEvent(
+        event="copilot_response",
+        data={
+            "response_category": "signature",
+            "completeness": ResponseCompleteness.COMPLETE.value,
+            "version": version,
+            "signature": signature,
+            "assistant_message": assistant_message.model_dump(),
+        },
+    )
+
+
+async def create_signature_envelope_for_handler(
+    req: CopilotRequest, handler: CopilotResponseHandler
+) -> Optional[ServerSentEvent]:
+    """Create a signature SSE envelope from the accumulated handler output.
+
+    Args:
+        req: Request object containing copilot chat history and session ID.
+        handler: The response handler containing generated responses.
+
+    Returns:
+        Optional[ServerSentEvent]: SSE envelope with signature data or None if
+        signing is not applicable.
+    """
+    text, category = extract_full_text_and_category(handler)
+    return await create_signature_envelope_for_text(req, text, category)
+
+
+def extract_full_text_and_category(handler: Any) -> Tuple[str, ResponseCategory]:
+    """Extract full text and response category from the handler's generated responses.
+
+    Args:
+        handler: The response handler containing generated responses.
+
+    Returns:
+        Tuple[str, ResponseCategory]: Concatenated text and the last response category.
+    """
+    text_parts: List[str] = []
+    last_category: Optional[ResponseCategory] = None
+
+    for response in getattr(handler, "generated_responses", []) or []:
+        content = getattr(response, "content", None)
+        if isinstance(response, GeneratedContent) and content:
+            text_parts.append(content)
+            category = getattr(response, "response_category", None)
+            if category and category not in {
+                ResponseCategory.REFERENCE,
+                ResponseCategory.REFERENCE_ENTRY,
+            }:
+                last_category = category
+
+    return "".join(text_parts), (last_category or ResponseCategory.COPILOT)

rasa/builder/copilot/telemetry.py

@@ -0,0 +1,234 @@
+import datetime as dt
+import os
+import uuid
+from typing import Any, Iterable, Optional, Sequence
+
+import structlog
+
+from rasa import telemetry
+from rasa.builder.copilot.constants import COPILOT_SEGMENT_WRITE_KEY_ENV_VAR
+from rasa.builder.copilot.copilot_response_handler import CopilotResponseHandler
+from rasa.builder.copilot.models import EventContent
+from rasa.builder.document_retrieval.models import Document
+from rasa.telemetry import (
+    SEGMENT_TRACK_ENDPOINT,
+    segment_request_payload,
+    send_segment_request,
+    with_default_context_fields,
+)
+
+structlogger = structlog.get_logger()
+
+COPILOT_USER_MESSAGE_EVENT = "copilot_user_message"
+COPILOT_BOT_MESSAGE_EVENT = "copilot_bot_message"
+
+COPILOT_SEGMENT_WRITE_KEY = os.getenv(COPILOT_SEGMENT_WRITE_KEY_ENV_VAR)
+if _SEGMENT_ON := bool(COPILOT_SEGMENT_WRITE_KEY):
+    structlogger.info("builder.telemetry.enabled")
+else:
+    structlogger.warning("builder.telemetry.disabled")
+
+
+def _track(event: str, user_id: str, properties: dict) -> None:
+    """Track an event with Segment.
+
+    Args:
+        event: The name of the event to track.
+        user_id: The ID of the user associated with the event.
+        properties: Additional properties to include with the event.
+
+    Raises:
+        Exception: If tracking fails, an exception is logged.
+    """
+    if not _SEGMENT_ON or not telemetry.is_telemetry_enabled():
+        structlogger.debug("builder.telemetry._track.disabled")
+        return
+    structlogger.debug("builder.telemetry._track.enabled")
+
+    try:
+        payload = segment_request_payload(
+            user_id, event, properties, context=with_default_context_fields()
+        )
+        structlogger.debug("builder.telemetry._track.sending", payload=payload)
+
+        send_segment_request(SEGMENT_TRACK_ENDPOINT, payload, COPILOT_SEGMENT_WRITE_KEY)
+    except Exception as e:  # skipcq:PYL-W0703
+        structlogger.warning("builder.telemetry.track_failed", error=str(e))
+
+
+class CopilotTelemetry:
+    def __init__(
+        self,
+        *,
+        project_id: str,
+        user_id: str,
+    ) -> None:
+        """Initialize Telemetry instance."""
+        self._project_id = project_id
+        self._user_id = user_id
+        # TODO Load prompt version
+        self._prompt_version = "1"
+
+    def log_user_turn(self, text: str) -> None:
+        """Track a user message in the conversation.
+
+        Args:
+            text: The text of the user message.
+        """
+        structlogger.debug("builder.telemetry.log_user_turn", text=text)
+        _track(
+            COPILOT_USER_MESSAGE_EVENT,
+            self._user_id,
+            {
+                "project_id": self._project_id,
+                "message_id": uuid.uuid4().hex,
+                "text": text,
+                "timestamp": dt.datetime.utcnow().isoformat(),
+            },
+        )
+
+    def log_copilot_turn(
+        self,
+        *,
+        text: str,
+        source_urls: Sequence[str],
+        flags: Iterable[str],
+        latency_ms: int,
+        model: str,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+        total_tokens: Optional[int] = None,
+        system_message: Optional[dict[str, Any]] = None,
+        chat_history: Optional[list[dict[str, Any]]] = None,
+        last_user_message: Optional[str] = None,
+        tracker_event_attachments: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        """Track a copilot message in the conversation.
+
+        Args:
+            text: The text of the copilot message.
+            source_urls: URLs of the sources used to generate the response.
+            flags: Flags indicating special conditions or features.
+            latency_ms: End-to-end Copilot latency to produce this response.
+            model: The model used to generate the response.
+            input_tokens: Number of input tokens used (optional).
+            output_tokens: Number of output tokens generated (optional).
+            total_tokens: Total number of tokens used (input + output) (optional).
+            system_message: The system message used (optional).
+            chat_history: The chat history messages used (optional).
+            last_user_message: The last user message used (optional).
+            tracker_event_attachments: The tracker event attachments used (optional).
+        """
+        structlogger.debug("builder.telemetry.log_copilot_turn", text=text)
+
+        # FIXME: Temporarily remove the system_message from telemetry payload.
+        # Reason: It often exceeds Segment payload size limits, causing the request
+        # to be rejected and the event to be absent in Segment. Instead, temporarily
+        # log the system_message so it's visible in Grafana.
+        telemetry_data = {
+            "project_id": self._project_id,
+            "message_id": uuid.uuid4().hex,
+            "text": text,
+            "prompt_version": self._prompt_version,
+            "source_urls": list(source_urls),
+            "flags": list(flags),
+            "latency_ms": latency_ms,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "total_tokens": total_tokens,
+            "chat_history": chat_history,
+            "last_user_message": last_user_message,
+            "tracker_event_attachments": tracker_event_attachments,
+            "timestamp": dt.datetime.utcnow().isoformat(),
+        }
+
+        # Log all telemetry data plus system_message for debugging
+        log_data = telemetry_data.copy()
+        if system_message:
+            log_data["system_message"] = system_message
+
+        structlogger.info("builder.telemetry.copilot_turn", **log_data)
+
+        _track(
+            COPILOT_BOT_MESSAGE_EVENT,
+            self._user_id,
+            telemetry_data,
+        )
+
+    @staticmethod
+    def _extract_flags(handler: CopilotResponseHandler) -> list[str]:
+        """Extract flags from the response handler.
+
+        Args:
+            handler: The response handler containing generated responses.
+
+        Returns:
+            A list of flags indicating special conditions or features.
+        """
+        flags = {r.response_category.value for r in handler.generated_responses}
+        return sorted(flags)
+
+    @staticmethod
+    def _full_text(handler: CopilotResponseHandler) -> str:
+        """Extract full text from the response handler.
+
+        Args:
+            handler: The response handler containing generated responses.
+
+        Returns:
+            The concatenated content of all generated responses.
+        """
+        return "".join(
+            response.content
+            for response in handler.generated_responses
+            if getattr(response, "content", None)
+        )
+
+    def log_copilot_from_handler(
+        self,
+        *,
+        handler: CopilotResponseHandler,
+        used_documents: list[Document],
+        latency_ms: int,
+        model: str,
+        prompt_tokens: int,
+        completion_tokens: int,
+        total_tokens: int,
+        system_message: dict[str, Any],
+        chat_history: list[dict[str, Any]],
+        last_user_message: Optional[str],
+        tracker_event_attachments: list[EventContent],
+    ) -> None:
+        """Log a copilot message from the response handler.
+
+        Args:
+            handler: The response handler containing generated responses.
+            used_documents: List of documents used as supporting evidence.
+            latency_ms: End-to-end Copilot latency to produce this response.
+            model: The model used to generate the response.
+            prompt_tokens: Number of input tokens used.
+            completion_tokens: Number of output tokens generated.
+            total_tokens: Total number of tokens used (input + output).
+            system_message: The system message used.
+            chat_history: The chat history messages used.
+            last_user_message: The last user message used.
+        """
+        structlogger.debug("builder.telemetry.log_copilot_from_handler")
+        text = self._full_text(handler)
+        self.log_copilot_turn(
+            text=text,
+            source_urls=[d.url for d in used_documents if d.url],
+            flags=self._extract_flags(handler),
+            latency_ms=latency_ms,
+            model=model,
+            input_tokens=prompt_tokens,
+            output_tokens=completion_tokens,
+            total_tokens=total_tokens,
+            system_message=system_message,
+            chat_history=chat_history,
+            last_user_message=last_user_message,
+            tracker_event_attachments=[
+                attachment.model_dump() for attachment in tracker_event_attachments
+            ],
+        )

rasa/builder/copilot/templated_messages/copilot_internal_messages_templates.yml

@@ -0,0 +1,16 @@
+# Templates for role ROLE_RASA_INTERNAL
+# Note: Only 'training_error_log_analysis' and 'e2e_testing_error_log_analysis' are
+# valid response categories for rasa internal messages for now.
+# Future contexts can be added here + in ResponseCategory enumeration.
+
+templates:
+  # Templated utterance when training fails.
+  training_error_log_analysis: |
+    The assistant training failed. Your task is to analyze provided error logs
+    and help me fix the issue.
+
+  # Templated utterance when e2e testing fails.
+  e2e_testing_error_log_analysis: |
+    The e2e testing failed. Your task is to analyze provided error from the E2E
+    test logs and help me fix the issue. Help me understand if the issue is within
+    the the E2E test or the assistant.