rasa-pro 3.14.0.dev20250825__py3-none-any.whl → 3.14.0.dev20250901__py3-none-any.whl

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,200 @@
+import datetime as dt
+import os
+import uuid
+from typing import 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.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_prompt: Optional[str] = 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).
+        """
+        structlogger.debug("builder.telemetry.log_copilot_turn", text=text)
+        _track(
+            COPILOT_BOT_MESSAGE_EVENT,
+            self._user_id,
+            {
+                "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,
+                "system_prompt": system_prompt,
+                "timestamp": dt.datetime.utcnow().isoformat(),
+            },
+        )
+
+    @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_prompt: str,
+    ) -> 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_prompt: The system prompt 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_prompt=system_prompt,
+        )

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.

rasa/builder/copilot/templated_messages/copilot_templated_responses.yml

@@ -0,0 +1,38 @@
+responses:
+  roleplay_response: |
+    Looks like we’ve slipped into chatting as if I were your bot. I’m here to help you
+    build and improve your Rasa agent, not to roleplay as it. If you'd like to test your
+    agent, add your message in the chat preview on the right. If you’re not sure what to
+    test, I can help you create a new skill or suggest a few example conversations to
+    try.
+
+  out_of_scope_response: |
+    I’m here to help you build and improve your Rasa chatbot. I can explain concepts,
+    walk you through changes, or debug things with you.
+    
+    Do you want me to show you what your assistant can do right now, or help you add
+    something new?
+
+  error_fallback_response: |
+    Your project ran into an error, but I'm not sure what caused it. Take a look at the
+    logs for the full details.
+
+  guardrail_policy_violation_response: |
+    I’m here to help you with Rasa agent development in a safe and respectful
+    environment. I cannot assist with harmful content, inappropriate material, or
+    attempts to manipulate my responses. Continued attempts to use the system in this
+    way may result in project termination and account blocking.
+
+  copilot_redacted_message: "[Copilot response redacted for guardrails check.]"
+
+  knowledge_base_access_requested_response: |
+    At the moment I can't read your knowledge base directly, but you can browse the
+    available entries in the `/docs` folder in your code editor. 
+
+  guardrail_blocked_user_response: |
+    Your Copilot access has been temporarily blocked due to repeated policy violations.
+    If you believe this is an error or would like to request a review, please reach out to support@rasa.com.
+
+  guardrail_blocked_project_response: |
+    Your Copilot access has been temporarily blocked due to repeated policy violations.
+    If you believe this is an error or would like to request a review, please reach out to support@rasa.com.

rasa/builder/document_retrieval/constants.py

@@ -0,0 +1,15 @@
+import importlib_resources
+
+from rasa.constants import PACKAGE_NAME
+
+INKEEP_API_KEY_ENV_VAR = "INKEEP_API_KEY"
+
+INKEEP_RAG_RESPONSE_SCHEMA_PATH = str(
+    importlib_resources.files(PACKAGE_NAME)
+    .joinpath("builder")
+    .joinpath("document_retrieval")
+    .joinpath("inkeep-rag-response-schema.json")
+)
+
+
+INKEEP_DOCUMENT_RETRIEVAL_MODEL = "inkeep-rag"

rasa/builder/document_retrieval/inkeep-rag-response-schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "content": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string"
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string"
+                    },
+                    "media_type": {
+                      "type": "string"
+                    },
+                    "text": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "type": {
+                "type": "string"
+              },
+              "media_type": {
+                "type": "string"
+              },
+              "data": {
+                "type": "string"
+              }
+            }
+          },
+          "title": {
+            "type": "string"
+          },
+          "context": {
+            "type": "string"
+          },
+          "record_type": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "required": ["content"]
+}