rasa-pro 3.14.0rc1__py3-none-any.whl → 3.14.0rc3__py3-none-any.whl

rasa/builder/copilot/models.py

@@ -1,16 +1,23 @@
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Type, TypeVar, Union
 
 import structlog
 from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
-from pydantic import BaseModel, Field, field_serializer, model_validator
+from pydantic import (
+    BaseModel,
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
 from typing_extensions import Annotated
 
 from rasa.builder.copilot.constants import (
     ROLE_ASSISTANT,
     ROLE_COPILOT,
     ROLE_COPILOT_INTERNAL,
+    ROLE_SYSTEM,
     ROLE_USER,
 )
 from rasa.builder.document_retrieval.models import Document
@@ -49,7 +56,8 @@ class ResponseCategory(Enum):
     # When Copilot analyzes error logs and provides suggestions
     TRAINING_ERROR_LOG_ANALYSIS = "training_error_log_analysis"
     E2E_TESTING_ERROR_LOG_ANALYSIS = "e2e_testing_error_log_analysis"
-
+    TRAINING_ERROR_LOG = "training_error_log"
+    E2E_TESTING_ERROR_LOG = "e2e_testing_error_log"
     # Conversation history signature
     SIGNATURE = "signature"
 
@@ -90,7 +98,7 @@ class LogContent(BaseContent):
     type: Literal["log"]
     content: str = Field(..., description="Logs, error messages, stack traces, etc.")
     context: Optional[str] = Field(
-        None,
+        default=None,
         description=(
             "Additional, optional context description for the logs "
             "(e.g., 'training session', 'e2e testing run', 'deployment process')"
@@ -102,7 +110,7 @@ class LogContent(BaseContent):
     )
 
 
-class EventContent(BaseModel):
+class EventContent(BaseContent):
     type: Literal["event"]
     event: str = Field(..., description="The event's type_name")
 
@@ -144,125 +152,220 @@ ContentBlock = Annotated[
     ),
 ]
 
+TContentBlock = TypeVar("TContentBlock", bound=BaseContent)
 
-class CopilotChatMessage(BaseModel):
-    """Model for a single chat messages between the user and the copilot."""
 
-    role: str = Field(
-        ...,
-        pattern=f"^({ROLE_USER}|{ROLE_COPILOT}|{ROLE_COPILOT_INTERNAL})$",
-        description="The role of the message sender.",
-    )
+class BaseCopilotChatMessage(BaseModel, ABC):
+    role: str
+    response_category: Optional[ResponseCategory] = Field(default=None)
+
+    @abstractmethod
+    def build_openai_message(self, *args, **kwargs) -> Dict[str, Any]:  # type: ignore[no-untyped-def]
+        pass
+
+    @field_serializer("response_category", when_used="always")
+    def _serialize_response_category(
+        self, v: Optional[ResponseCategory]
+    ) -> Optional[str]:
+        """Serializing CopilotChatMessage, response_category should be a string."""
+        return None if v is None else v.value
+
+
+class BaseContentBlockCopilotChatMessage(BaseCopilotChatMessage, ABC):
+    """Base class for messages that contain ContentBlock lists."""
+
     content: List[ContentBlock]
-    response_category: Optional[ResponseCategory] = Field(
-        None,
-        description=(
-            "The category/source of this message. For user role messages, only `None` "
-            "or `GUARDRAILS_POLICY_VIOLATION` are allowed. For copilot role messages, "
-            "any category is permitted."
-        ),
+
+    def get_flattened_text_content(self) -> str:
+        """Get the text content from the message."""
+        return "\n".join(
+            content_block.text
+            for content_block in self.content
+            if isinstance(content_block, TextContent)
+        )
+
+    def get_flattened_log_content(self) -> str:
+        """Get the log content from the message."""
+        return "\n".join(
+            content_block.content
+            for content_block in self.content
+            if isinstance(content_block, LogContent)
+        )
+
+    def get_content_blocks_by_type(
+        self, content_type: Type[TContentBlock]
+    ) -> List[TContentBlock]:
+        """Get the content blocks from the message by type."""
+        return [
+            content_block
+            for content_block in self.content
+            if isinstance(content_block, content_type)
+        ]
+
+
+class CopilotSystemMessage(BaseCopilotChatMessage):
+    role: Literal["system"] = Field(
+        default=ROLE_SYSTEM,
+        pattern=f"^{ROLE_SYSTEM}",
+        description="The system message that sets the system instructions for the LLM.",
     )
 
+    def build_openai_message(self, prompt: str, *args, **kwargs) -> Dict[str, Any]:  # type: ignore[no-untyped-def]
+        """Render the system message template and return OpenAI format."""
+        return {"role": ROLE_SYSTEM, "content": prompt}
+
+
+class UserChatMessage(BaseContentBlockCopilotChatMessage):
+    role: Literal["user"] = Field(
+        default=ROLE_USER,
+        pattern=f"^{ROLE_USER}",
+        description="The user who sent the message.",
+    )
+
+    @classmethod
+    @field_validator("content")
+    def must_have_at_least_one_text(cls, v: List[ContentBlock]) -> List[ContentBlock]:
+        if not any(isinstance(content_block, TextContent) for content_block in v):
+            message = "User role messages must have at least one `TextContent` block."
+            structlogger.error(
+                "user_chat_message.missing_text_content",
+                event_info=message,
+                content=v,
+            )
+            raise ValueError(
+                "UserChatMessage must contain at least one TextContent block."
+            )
+        return v
+
     @model_validator(mode="after")
-    def validate_response_category_for_role(self) -> "CopilotChatMessage":
-        """Validate value of response_category for the role of the message.
+    def validate_response_category(self) -> "UserChatMessage":
+        """Validate value of response_category for user message.
 
         For 'user' role messages, only None or GUARDRAILS_POLICY_VIOLATION are allowed.
-        For 'copilot' role messages, any category is permitted.
-        For 'rasa_internal' role messages, any category is permitted.
         """
+        allowed_response_categories = [ResponseCategory.GUARDRAILS_POLICY_VIOLATION]
         if (
-            self.role == ROLE_USER
-            and self.response_category is not None
-            and self.response_category != ResponseCategory.GUARDRAILS_POLICY_VIOLATION
+            self.response_category is not None
+            and self.response_category not in allowed_response_categories
         ):
             message = (
                 f"User role messages can only have response_category of `None` or "
-                f"`{ResponseCategory.GUARDRAILS_POLICY_VIOLATION}`, "
-                f"got `{self.response_category}`."
+                f"{', '.join(category.value for category in allowed_response_categories)}."  # noqa: E501
+                f"Got `{self.response_category}`."
             )
             structlogger.error(
-                "copilot_chat_message.validate_response_category_for_role"
+                "user_chat_message.validate_response_category"
                 ".invalid_response_category",
                 event_info=message,
                 response_category=self.response_category,
+                allowed_response_categories=allowed_response_categories,
                 role=self.role,
             )
             raise ValueError(message)
 
         return self
 
-    @field_serializer("response_category", when_used="always")
-    def _serialize_response_category(
-        self, v: Optional[ResponseCategory]
-    ) -> Optional[str]:
-        """Serializing CopilotChatMessage, response_category should be a string."""
-        return None if v is None else v.value
-
-    def get_text_content(self) -> str:
-        """Concatenate all 'text' content blocks into a single string."""
-        return "\n".join(
-            content_block.text
-            for content_block in self.content
-            if isinstance(content_block, TextContent)
-        )
-
-    def get_log_content(self) -> str:
-        """Concatenate all 'log' content blocks into a single string."""
-        return "\n".join(
-            content_block.content
-            for content_block in self.content
-            if isinstance(content_block, LogContent)
-        )
+    def build_openai_message(  # type: ignore[no-untyped-def]
+        self, prompt: Optional[str] = None, *args, **kwargs
+    ) -> Dict[str, Any]:
+        # If a prompt is provided, add it to the message content as additional
+        # instructions
+        if prompt:
+            return {
+                "role": ROLE_USER,
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {"type": "text", "text": self.get_flattened_text_content()},
+                ],
+            }
+        # Return simple text content (useful for showing the history)
+        else:
+            return {"role": ROLE_USER, "content": self.get_flattened_text_content()}
 
-    def to_openai_format(self) -> Dict[str, Any]:
-        """Convert to OpenAI message format for API calls."""
-        role_to_openai_format = {
-            ROLE_USER: self._user_message_to_openai_format,
-            ROLE_COPILOT: self._copilot_message_to_openai_format,
-            ROLE_COPILOT_INTERNAL: self._copilot_message_to_openai_format,
-        }
-        return role_to_openai_format[self.role]()
 
-    def _user_message_to_openai_format(self) -> Dict[str, Any]:
-        role = self._map_role_to_openai()
-        content = self.get_text_content()
-        return {"role": role, "content": content}
+class CopilotChatMessage(BaseContentBlockCopilotChatMessage):
+    role: Literal["copilot"]
 
-    def _copilot_message_to_openai_format(self) -> Dict[str, Any]:
-        role = self._map_role_to_openai()
+    def build_openai_message(self, *args, **kwargs) -> Dict[str, Any]:  # type: ignore[no-untyped-def]
         # For now the Copilot responds only with the text content and all the content
         # is formatted as a markdown.
-        # TODO: Once we start predicting the files, and expecting other content blocks
-        #       we should update this.
-        content = self.get_text_content()
-        return {"role": role, "content": content}
-
-    def _map_role_to_openai(self) -> str:
-        """Map internal roles to OpenAI-compatible roles."""
-        role_mapping = {
-            ROLE_USER: ROLE_USER,
-            ROLE_COPILOT: ROLE_ASSISTANT,
-            ROLE_COPILOT_INTERNAL: ROLE_USER,
-        }
-        if self.role not in role_mapping.keys():
+        return {"role": ROLE_ASSISTANT, "content": self.get_flattened_text_content()}
+
+
+class InternalCopilotRequestChatMessage(BaseContentBlockCopilotChatMessage):
+    role: Literal["internal_copilot_request"]
+
+    @model_validator(mode="after")
+    def validate_response_category(self) -> "InternalCopilotRequestChatMessage":
+        """Validate value of response_category for internal copilot request message.
+
+        For 'internal_copilot_request' role messages, only `TRAINING_ERROR_LOG_ANALYSIS`
+        and `E2E_TESTING_ERROR_LOG_ANALYSIS` response categories are allowed.
+        """
+        allowed_response_categories = [
+            ResponseCategory.TRAINING_ERROR_LOG_ANALYSIS,
+            ResponseCategory.E2E_TESTING_ERROR_LOG_ANALYSIS,
+        ]
+        if self.response_category not in allowed_response_categories:
+            message = (
+                f"Copilot Internal Roles request messages can only have of "
+                f"{', '.join(category.value for category in allowed_response_categories)}. "  # noqa: E501
+                f"Got `{self.response_category}`."
+            )
             structlogger.error(
-                "copilot_chat_message.to_openai_format.invalid_role",
-                event_info=(
-                    f"Invalid role: `{self.role}`. "
-                    f"Only {', '.join(role_mapping.keys())} roles are supported."
-                ),
+                "internal_copilot_request_chat_message.validate_response_category"
+                ".invalid_response_category",
+                event_info=message,
+                response_category=self.response_category,
+                allowed_response_categories=allowed_response_categories,
                 role=self.role,
             )
-            raise ValueError(f"Invalid role: {self.role}")
+            raise ValueError(message)
+
+        return self
+
+    def build_openai_message(self, prompt: str, *args, **kwargs) -> Dict[str, Any]:  # type: ignore[no-untyped-def]
+        """Build OpenAI message with pre-rendered prompt.
+
+        The prompt should be rendered externally using the content from this message
+        (logs, files, any additional context outside of this message, etc.) before
+        being passed to this method.
+        """
+        return {"role": ROLE_USER, "content": prompt}
+
+
+# Union type for all possible chat message types
+ChatMessage = Union[
+    CopilotSystemMessage,
+    UserChatMessage,
+    CopilotChatMessage,
+    InternalCopilotRequestChatMessage,
+]
+
+
+class CopilotContext(BaseModel):
+    """Model containing the context used by the copilot to generate a response."""
+
+    assistant_logs: str = Field(default="")
+    assistant_files: Dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "The assistant files. Key is the file path, value is the file content."
+        ),
+    )
+    copilot_chat_history: List[ChatMessage] = Field(default_factory=list)
+    tracker_context: Optional[TrackerContext] = Field(default=None)
+
+    class Config:
+        """Config for LLMBuilderContext."""
 
-        return role_mapping[self.role]
+        arbitrary_types_allowed = True
 
 
 class CopilotRequest(BaseModel):
     """Request model for the copilot endpoint."""
 
-    copilot_chat_history: List[CopilotChatMessage] = Field(
+    copilot_chat_history: List[ChatMessage] = Field(
         ...,
         description=(
             "The chat history between the user and the copilot. "
@@ -285,8 +388,43 @@ class CopilotRequest(BaseModel):
         description='Signature scheme version (e.g. "v1").',
     )
 
+    @field_validator("copilot_chat_history", mode="before")
+    @classmethod
+    def parse_chat_history(cls, v: List[Dict[str, Any]]) -> List[ChatMessage]:
+        """Manually parse chat history messages based on role field."""
+        parsed_messages: List[ChatMessage] = []
+        available_roles = [ROLE_USER, ROLE_COPILOT, ROLE_COPILOT_INTERNAL]
+        for message_data in v:
+            role = message_data.get("role")
+
+            if role == ROLE_USER:
+                parsed_messages.append(UserChatMessage(**message_data))
+
+            elif role == ROLE_COPILOT:
+                parsed_messages.append(CopilotChatMessage(**message_data))
+
+            elif role == ROLE_COPILOT_INTERNAL:
+                parsed_messages.append(
+                    InternalCopilotRequestChatMessage(**message_data)
+                )
+
+            else:
+                message = (
+                    f"Unknown role '{role}' in chat message. "
+                    f"Available roles are: {', '.join(available_roles)}."
+                )
+                structlogger.error(
+                    "copilot_request.parse_chat_history.unknown_role",
+                    event_info=message,
+                    role=role,
+                    available_roles=available_roles,
+                )
+                raise ValueError(message)
+
+        return parsed_messages
+
     @property
-    def last_message(self) -> Optional[CopilotChatMessage]:
+    def last_message(self) -> Optional[ChatMessage]:
         """Get the last message from the copilot chat history."""
         if not self.copilot_chat_history:
             return None
@@ -315,6 +453,12 @@ class CopilotOutput(BaseModel, ABC):
         """Convert to SSE event format."""
         pass
 
+    @property
+    @abstractmethod
+    def sse_data(self) -> Dict[str, Any]:
+        """Extract the SSE data payload."""
+        pass
+
 
 class GeneratedContent(CopilotOutput):
     """Represents generated content from the LLM to be streamed."""
@@ -327,13 +471,18 @@ class GeneratedContent(CopilotOutput):
         """Convert to SSE event format."""
         return ServerSentEvent(
             event="copilot_response",
-            data={
-                "content": self.content,
-                "response_category": self.response_category.value,
-                "completeness": self.response_completeness.value,
-            },
+            data=self.sse_data,
         )
 
+    @property
+    def sse_data(self) -> Dict[str, Any]:
+        """Extract the SSE data payload."""
+        return {
+            "content": self.content,
+            "response_category": self.response_category.value,
+            "completeness": self.response_completeness.value,
+        }
+
 
 class ReferenceEntry(CopilotOutput):
     """Represents a reference entry with title and url."""
@@ -361,15 +510,20 @@ class ReferenceEntry(CopilotOutput):
         """Convert to SSE event format."""
         return ServerSentEvent(
             event="copilot_response",
-            data={
-                "index": self.index,
-                "title": self.title,
-                "url": self.url,
-                "response_category": self.response_category.value,
-                "completeness": self.response_completeness.value,
-            },
+            data=self.sse_data,
         )
 
+    @property
+    def sse_data(self) -> Dict[str, Any]:
+        """Extract the SSE data payload."""
+        return {
+            "index": self.index,
+            "title": self.title,
+            "url": self.url,
+            "response_category": self.response_category.value,
+            "completeness": self.response_completeness.value,
+        }
+
 
 class ReferenceSection(CopilotOutput):
     """Represents a reference section with documentation links."""
@@ -395,16 +549,21 @@ class ReferenceSection(CopilotOutput):
         """Convert to SSE event format."""
         return ServerSentEvent(
             event="copilot_response",
-            data={
-                "references": [
-                    reference.model_dump(include={"index", "title", "url"})
-                    for reference in self.references
-                ],
-                "response_category": self.response_category.value,
-                "completeness": self.response_completeness.value,
-            },
+            data=self.sse_data,
         )
 
+    @property
+    def sse_data(self) -> Dict[str, Any]:
+        """Extract the SSE data payload."""
+        return {
+            "references": [
+                reference.model_dump(include={"index", "title", "url"})
+                for reference in self.references
+            ],
+            "response_category": self.response_category.value,
+            "completeness": self.response_completeness.value,
+        }
+
     def sort_references(self) -> None:
         """Sort references by index value."""
         sorted_references = sorted(
@@ -414,18 +573,42 @@ class ReferenceSection(CopilotOutput):
         self.references = sorted_references
 
 
-class CopilotContext(BaseModel):
-    """Model containing the context used by the copilot to generate a response."""
+class TrainingErrorLog(CopilotOutput):
+    """Represents an error log."""
 
-    assistant_logs: str = Field("")
-    assistant_files: Dict[str, str] = Field({})
-    copilot_chat_history: List["CopilotChatMessage"] = Field([])
-    tracker_context: Optional[TrackerContext] = Field(None)
+    logs: List[LogContent]
+    response_category: ResponseCategory = Field(
+        default=ResponseCategory.TRAINING_ERROR_LOG,
+        frozen=True,
+    )
+    response_completeness: ResponseCompleteness = ResponseCompleteness.COMPLETE
 
-    class Config:
-        """Config for LLMBuilderContext."""
+    @model_validator(mode="after")
+    def validate_response_category(self) -> "TrainingErrorLog":
+        """Validate that response_category has the correct default value."""
+        if self.response_category != ResponseCategory.TRAINING_ERROR_LOG:
+            raise ValueError(
+                f"TrainingErrorLog response_category must be "
+                f"{ResponseCategory.TRAINING_ERROR_LOG}, "
+                f"got `{self.response_category}`."
+            )
+        return self
 
-        arbitrary_types_allowed = True
+    def to_sse_event(self) -> ServerSentEvent:
+        """Convert to SSE event format."""
+        return ServerSentEvent(
+            event="copilot_response",
+            data=self.sse_data,
+        )
+
+    @property
+    def sse_data(self) -> Dict[str, Any]:
+        """Extract the SSE data payload."""
+        return {
+            "logs": [log.model_dump() for log in self.logs],
+            "response_category": self.response_category.value,
+            "completeness": self.response_completeness.value,
+        }
 
 
 class UsageStatistics(BaseModel):
@@ -493,6 +676,13 @@ class CopilotGenerationContext(BaseModel):
     last_user_message: Optional[Dict[str, Any]] = Field(
         None, description="The last user message with context that was processed."
     )
+    tracker_event_attachments: List[EventContent] = Field(
+        ...,
+        description=(
+            "The tracker event attachments passed with the user message used as "
+            "an additional context."
+        ),
+    )
 
     class Config:
         """Config for CopilotGenerationContext."""

rasa/builder/copilot/prompts/copilot_system_prompt.jinja2

@@ -86,9 +86,9 @@ and panels.
 ***
 
 ## Layout
-- **Left Panel – Copilot Chat:** Where the user asks you for help, guidance, or troubleshooting.
-- **Center Panel – Playground Preview:** Main workspace with Chat Mode (default) or Inspect Mode.
-- **Right Panel – Inspector Visualization:** Real-time diagram of conversation logic (only in Inspect Mode).
+- **Left Panel - Copilot Chat:** Where the user asks you for help, guidance, or troubleshooting.
+- **Center Panel - Playground Preview:** Main workspace with Chat Mode (default) or Inspect Mode.
+- **Right Panel - Inspector Visualization:** Real-time diagram of conversation logic (only in Inspect Mode).
 
 ***
 
@@ -140,19 +140,40 @@ response.
 
 ***
 
+### 5. Sharing Attachments
+
+Users can share additional context with Copilot by clicking the "Ask Copilot" button
+while "Inspect Mode" is open. This sends selected conversation state as an attachment
+together with their question.
+
+The attachments are typically tracker events, which can be:
+- User messages - what the user typed or said.
+- Assistant messages - what the assistant responded with.
+- Actions - operations the assistant executed, including how they were chosen.
+- Slots - what slots were set or updated during the exchange.
+- Flows - when a flow starts, is interrupted, resumes, or completes.
+- Sessions - the beginning or end of a conversation session.
+
+**Tip:** Encourage users to use attachments to get to know the Rasa workings better. If 
+user is facing issues, these attachments will give Copilot a ground-truth trace of what
+actually happened in the assistant, making attachments a powerful tool for debugging.
+
+***
+
 ## Rasa CLI to Hello Rasa UI Mapping
 
 Map available features to **Rasa CLI** to the **Hello Rasa Action**, so users see
 continuity. 
 
-| Feature              | Rasa CLI          | Hello Rasa Action         |
-|----------------------|-----------------------|---------------------------|
-| Train assistant      | `rasa train`          | Apply Changes             |
-| Test conversation    | `rasa shell`          | Chat Mode                 |
-| Debug conversation   | `rasa shell --debug`  | Inspect Mode              |
-| Run custom actions   | `rasa run actions`    | Code Mode + Apply Changes |
-| Export project files | —                     | Download button           |
-| Edit project files   | —                     | Code Mode                 |
+| Feature                  | Rasa CLI              | Hello Rasa Action                  |
+|--------------------------|-----------------------|------------------------------------|
+| Train assistant          | `rasa train`          | Apply Changes                      |
+| Test conversation        | `rasa shell`          | Chat Mode                          |
+| Debug conversation       | `rasa shell --debug`  | Inspect Mode                       |
+| Run custom actions       | `rasa run actions`    | Code Mode + Apply Changes          |
+| Export project files     | —                     | Download button                    |
+| Edit project files       | —                     | Code Mode                          |
+| Share conversation trace | `rasa shell --debug`  | Ask Copilot button in Inspect Mode |
 
 **Note:** Ignore any references to *Rasa Studio*.
 
@@ -181,7 +202,7 @@ code change, or reference). It should be:
 - **Friendly, but Focused**: Use a warm and conversational style, but stay precise and technically correct.  
 - **Confident & Trustworthy**: Present guidance as clear and reliable; avoid hedging unless there's genuine uncertainty (in which case, ask clarifying questions).
 - **Brand-Positive**: Highlight the strengths of **Rasa** and **Hello Rasa**, when appropriate, framing them as powerful and easy to use.
-- **Code-style references** – You MUST wrap all flow names, slot names, variables, and any part of the user's code in backticks (e.g., `slot_name`, `flow_name`, `variable_name`). This is mandatory formatting.
+- **Code-style references**: You MUST wrap all flow names, slot names, variables, and any part of the user's code in backticks (e.g., `slot_name`, `flow_name`, `variable_name`). This is mandatory formatting.
 
 ***