rasa-pro 3.12.18.dev1__py3-none-any.whl → 3.13.0a1.dev2__py3-none-any.whl

rasa/shared/importers/static.py

@@ -0,0 +1,63 @@
+import logging
+from typing import Dict, Optional, Text
+
+from rasa.shared.core.domain import Domain
+from rasa.shared.core.flows import FlowsList
+from rasa.shared.core.training_data.structures import StoryGraph
+from rasa.shared.importers.importer import TrainingDataImporter
+from rasa.shared.nlu.training_data.training_data import TrainingData
+from rasa.shared.utils.common import cached_method
+
+logger = logging.getLogger(__name__)
+
+
+class StaticTrainingDataImporter(TrainingDataImporter):
+    """Static `TrainingFileImporter` implementation."""
+
+    def __init__(
+        self,
+        domain: Domain,
+        stories: Optional[StoryGraph] = None,
+        flows: Optional[FlowsList] = None,
+        nlu_data: Optional[TrainingData] = None,
+        config: Optional[Dict] = None,
+    ):
+        self.domain = domain
+        self.stories = stories or StoryGraph([])
+        self.flows = flows or FlowsList(underlying_flows=[])
+        self.nlu_data = nlu_data or TrainingData()
+        self.config = config or {}
+
+    @cached_method
+    def get_config(self) -> Dict:
+        """Retrieves model config (see parent class for full docstring)."""
+        return self.config
+
+    def get_config_file_for_auto_config(self) -> Optional[Text]:
+        """Returns config file path for auto-config only if there is a single one."""
+        return None
+
+    @cached_method
+    def get_stories(self, exclusion_percentage: Optional[int] = None) -> StoryGraph:
+        """Retrieves training stories / rules (see parent class for full docstring)."""
+        return self.stories
+
+    @cached_method
+    def get_flows(self) -> FlowsList:
+        """Retrieves training stories / rules (see parent class for full docstring)."""
+        return self.flows
+
+    @cached_method
+    def get_conversation_tests(self) -> StoryGraph:
+        """Retrieves conversation test stories (see parent class for full docstring)."""
+        return StoryGraph([])
+
+    @cached_method
+    def get_nlu_data(self, language: Optional[Text] = "en") -> TrainingData:
+        """Retrieves NLU training data (see parent class for full docstring)."""
+        return self.nlu_data
+
+    @cached_method
+    def get_domain(self) -> Domain:
+        """Retrieves model domain (see parent class for full docstring)."""
+        return self.domain

rasa/shared/providers/constants.py

@@ -4,12 +4,3 @@ LITE_LLM_API_KEY_FIELD = "api_key"
 LITE_LLM_API_VERSION_FIELD = "api_version"
 LITE_LLM_MODEL_FIELD = "model"
 LITE_LLM_AZURE_AD_TOKEN = "azure_ad_token"
-
-# Enable or disable Langfuse integration
-RASA_LANGFUSE_INTEGRATION_ENABLED_ENV_VAR = "RASA_LANGFUSE_INTEGRATION_ENABLED"
-# Langfuse configuration
-LANGFUSE_CALLBACK_NAME = "langfuse"
-LANGFUSE_HOST_ENV_VAR = "LANGFUSE_HOST"
-LANGFUSE_PROJECT_ID_ENV_VAR = "LANGFUSE_PROJECT_ID"
-LANGFUSE_PUBLIC_KEY_ENV_VAR = "LANGFUSE_PUBLIC_KEY"
-LANGFUSE_SECRET_KEY_ENV_VAR = "LANGFUSE_SECRET_KEY"

rasa/shared/providers/llm/_base_litellm_client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 from abc import abstractmethod
-from typing import Any, Dict, List, Optional, Union, cast
+from typing import Any, Dict, List, Union, cast
 
 import structlog
 from litellm import acompletion, completion, validate_environment
@@ -126,11 +126,7 @@ class _BaseLiteLLMClient:
             raise ProviderClientValidationError(event_info)
 
     @suppress_logs(log_level=logging.WARNING)
-    def completion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> LLMResponse:
+    def completion(self, messages: Union[List[dict], List[str], str]) -> LLMResponse:
         """Synchronously generate completions for given list of messages.
 
         Args:
@@ -142,7 +138,6 @@ class _BaseLiteLLMClient:
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
 
         Returns:
             List of message completions.
@@ -160,9 +155,7 @@ class _BaseLiteLLMClient:
 
     @suppress_logs(log_level=logging.WARNING)
     async def acompletion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
+        self, messages: Union[List[dict], List[str], str]
     ) -> LLMResponse:
         """Asynchronously generate completions for given list of messages.
 
@@ -175,7 +168,6 @@ class _BaseLiteLLMClient:
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
 
         Returns:
             List of message completions.
@@ -186,9 +178,7 @@ class _BaseLiteLLMClient:
         try:
             formatted_messages = self._get_formatted_messages(messages)
             arguments = resolve_environment_variables(self._completion_fn_args)
-            response = await acompletion(
-                messages=formatted_messages, metadata=metadata, **arguments
-            )
+            response = await acompletion(messages=formatted_messages, **arguments)
             return self._format_response(response)
         except Exception as e:
             message = ""

rasa/shared/providers/llm/default_litellm_llm_client.py

@@ -101,11 +101,11 @@ class DefaultLiteLLMClient(_BaseLiteLLMClient):
         #       SageMaker) in Rasa by allowing AWS secrets to be provided as extra
         #       parameters without triggering validation errors due to missing AWS
         #       environment variables.
-        if self.provider.lower() in [
+        if self.provider.lower() in {
             AWS_BEDROCK_PROVIDER,
             AWS_SAGEMAKER_PROVIDER,
             AWS_SAGEMAKER_CHAT_PROVIDER,
-        ]:
+        }:
             validate_aws_setup_for_litellm_clients(
                 self._litellm_model_name,
                 self._litellm_extra_parameters,

rasa/shared/providers/llm/litellm_router_llm_client.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Union
 
 import structlog
 
@@ -122,12 +122,9 @@ class LiteLLMRouterLLMClient(_BaseLiteLLMRouterClient, _BaseLiteLLMClient):
             raise ProviderClientAPIException(e)
 
     @suppress_logs(log_level=logging.WARNING)
-    def completion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> LLMResponse:
-        """Synchronously generate completions for given list of messages.
+    def completion(self, messages: Union[List[dict], List[str], str]) -> LLMResponse:
+        """
+        Synchronously generate completions for given list of messages.
 
         Method overrides the base class method to call the appropriate
         completion method based on the configuration. If the chat completions
@@ -143,11 +140,8 @@ class LiteLLMRouterLLMClient(_BaseLiteLLMRouterClient, _BaseLiteLLMClient):
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
-
         Returns:
             List of message completions.
-
         Raises:
             ProviderClientAPIException: If the API request fails.
         """
@@ -164,11 +158,10 @@ class LiteLLMRouterLLMClient(_BaseLiteLLMRouterClient, _BaseLiteLLMClient):
 
     @suppress_logs(log_level=logging.WARNING)
     async def acompletion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
+        self, messages: Union[List[dict], List[str], str]
     ) -> LLMResponse:
-        """Asynchronously generate completions for given list of messages.
+        """
+        Asynchronously generate completions for given list of messages.
 
         Method overrides the base class method to call the appropriate
         completion method based on the configuration. If the chat completions
@@ -184,11 +177,8 @@ class LiteLLMRouterLLMClient(_BaseLiteLLMRouterClient, _BaseLiteLLMClient):
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
-
         Returns:
             List of message completions.
-
         Raises:
             ProviderClientAPIException: If the API request fails.
         """

rasa/shared/providers/llm/llm_client.py

@@ -1,19 +1,21 @@
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Protocol, Union, runtime_checkable
+from typing import Dict, List, Protocol, Union, runtime_checkable
 
 from rasa.shared.providers.llm.llm_response import LLMResponse
 
 
 @runtime_checkable
 class LLMClient(Protocol):
-    """Protocol for an LLM client that specifies the interface for interacting
+    """
+    Protocol for an LLM client that specifies the interface for interacting
     with the API.
     """
 
     @classmethod
     def from_config(cls, config: dict) -> LLMClient:
-        """Initializes the llm client with the given configuration.
+        """
+        Initializes the llm client with the given configuration.
 
         This class method should be implemented to parse the given
         configuration and create an instance of an llm client.
@@ -22,24 +24,17 @@ class LLMClient(Protocol):
 
     @property
     def config(self) -> Dict:
-        """Returns the configuration for that the llm client is initialized with.
+        """
+        Returns the configuration for that the llm client is initialized with.
 
         This property should be implemented to return a dictionary containing
         the configuration settings for the llm client.
         """
         ...
 
-    def completion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> LLMResponse:
-        """Synchronously generate completions for given list of messages.
-        def completion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
-        ) -> LLMResponse:
+    def completion(self, messages: Union[List[dict], List[str], str]) -> LLMResponse:
+        """
+        Synchronously generate completions for given list of messages.
 
         This method should be implemented to take a list of messages (as
         strings) and return a list of completions (as strings).
@@ -53,19 +48,16 @@ class LLMClient(Protocol):
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
-
         Returns:
             LLMResponse
         """
         ...
 
     async def acompletion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
+        self, messages: Union[List[dict], List[str], str]
     ) -> LLMResponse:
-        """Asynchronously generate completions for given list of messages.
+        """
+        Asynchronously generate completions for given list of messages.
 
         This method should be implemented to take a list of messages (as
         strings) and return a list of completions (as strings).
@@ -79,15 +71,14 @@ class LLMClient(Protocol):
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
-
         Returns:
             LLMResponse
         """
         ...
 
     def validate_client_setup(self, *args, **kwargs) -> None:  # type: ignore
-        """Perform client setup validation.
+        """
+        Perform client setup validation.
 
         This method should be implemented to validate whether the client can be
         used with the parameters provided through configuration or environment

rasa/shared/providers/llm/self_hosted_llm_client.py

@@ -237,9 +237,7 @@ class SelfHostedLLMClient(_BaseLiteLLMClient):
             raise ProviderClientAPIException(e)
 
     async def acompletion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
+        self, messages: Union[List[dict], List[str], str]
     ) -> LLMResponse:
         """Asynchronous completion of the model with the given messages.
 
@@ -257,7 +255,6 @@ class SelfHostedLLMClient(_BaseLiteLLMClient):
                 - a list of messages. Each message is a string and will be formatted
                     as a user message.
                 - a single message as a string which will be formatted as user message.
-            metadata: Optional metadata to be passed to the LLM call.
 
         Returns:
             The completion response.
@@ -266,11 +263,7 @@ class SelfHostedLLMClient(_BaseLiteLLMClient):
             return await super().acompletion(messages)
         return await self._atext_completion(messages)
 
-    def completion(
-        self,
-        messages: Union[List[dict], List[str], str],
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> LLMResponse:
+    def completion(self, messages: Union[List[dict], List[str], str]) -> LLMResponse:
         """Completion of the model with the given messages.
 
         Method overrides the base class method to call the appropriate
@@ -280,7 +273,6 @@ class SelfHostedLLMClient(_BaseLiteLLMClient):
 
         Args:
             messages: The messages to be used for completion.
-            metadata: Optional metadata to be passed to the LLM call.
 
         Returns:
             The completion response.

rasa/shared/utils/common.py

@@ -1,4 +1,5 @@
 import asyncio
+import copy
 import functools
 import importlib
 import inspect
@@ -288,6 +289,47 @@ def merge_lists_of_dicts(
     return list(merged_dicts.values())
 
 
+def partial_merge_list(
+    self_list: List[Any],
+    other_list: List[Any],
+    is_same_item_fn: Callable[[Any, Any], bool],
+) -> List[Any]:
+    """Merges two lists based on a custom intersection logic."""
+    matched_other_indices = set()
+    result = []
+
+    for s_item in self_list:
+        match = next(
+            (
+                (i, o_item)
+                for i, o_item in enumerate(other_list)
+                if i not in matched_other_indices and is_same_item_fn(s_item, o_item)
+            ),
+            None,
+        )
+        if match:
+            i, o_item = match
+            result.append(copy.deepcopy(o_item))
+            matched_other_indices.add(i)
+        else:
+            result.append(copy.deepcopy(s_item))
+
+    return result
+
+
+def partial_merge_dict(
+    self_d: Dict[Text, Any], other_d: Dict[Text, Any]
+) -> Dict[Text, Any]:
+    """Merges two dictionaries based on a custom intersection logic."""
+    merged = {}
+    for k, v in self_d.items():
+        if k in other_d:
+            merged[k] = copy.deepcopy(other_d[k])
+        else:
+            merged[k] = copy.deepcopy(v)
+    return merged
+
+
 def warn_and_exit_if_module_path_contains_rasa_plus(
     module_path: Text, lookup_path: Optional[str] = None
 ) -> None:
@@ -342,7 +384,7 @@ def display_research_study_prompt() -> None:
 {separator}
 Want to help shape the future of Rasa Pro?
 Share your feedback in a short conversation with our team.
-Sign up at: https://calendly.com/alvaro-rasa/rasa-pro-installation
+Sign up at: https://rasa.com/book-feedback-call
 {separator}
 """
     print_success(message)

rasa/shared/utils/llm.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import importlib.resources
 import json
 import logging
@@ -20,15 +22,23 @@ from typing import (
 )
 
 import structlog
+from pydantic import BaseModel, Field
 
 import rasa.shared.utils.io
-from rasa.core.utils import AvailableEndpoints
+from rasa.core.available_endpoints import AvailableEndpoints
 from rasa.shared.constants import (
+    CONFIG_NAME_KEY,
+    CONFIG_PIPELINE_KEY,
+    CONFIG_POLICIES_KEY,
     DEFAULT_PROMPT_PACKAGE_NAME,
+    LLM_CONFIG_KEY,
     MODEL_CONFIG_KEY,
     MODEL_GROUP_CONFIG_KEY,
     MODEL_GROUP_ID_CONFIG_KEY,
+    MODEL_GROUPS_CONFIG_KEY,
     MODELS_CONFIG_KEY,
+    PROMPT_CONFIG_KEY,
+    PROMPT_TEMPLATE_CONFIG_KEY,
     PROVIDER_CONFIG_KEY,
     RASA_PATTERN_INTERNAL_ERROR_USER_INPUT_EMPTY,
     RASA_PATTERN_INTERNAL_ERROR_USER_INPUT_TOO_LONG,
@@ -63,6 +73,7 @@ from rasa.shared.providers.mappings import (
     get_embedding_client_from_provider,
     get_llm_client_from_provider,
 )
+from rasa.shared.utils.common import all_subclasses
 from rasa.shared.utils.constants import LOG_COMPONENT_SOURCE_METHOD_INIT
 
 if TYPE_CHECKING:
@@ -110,6 +121,18 @@ _CombineConfigs_F = TypeVar(
 )
 
 
+class SystemPrompts(BaseModel):
+    command_generator: str = Field(
+        ..., description="Prompt used by the LLM command generator."
+    )
+    enterprise_search: str = Field(
+        ..., description="Prompt for standard enterprise search requests."
+    )
+    contextual_response_rephraser: str = Field(
+        ..., description="Prompt used for re-phrasing assistant responses."
+    )
+
+
 def _compute_hash_for_cache_from_configs(
     config_x: Dict[str, Any], config_y: Dict[str, Any]
 ) -> int:
@@ -821,7 +844,9 @@ def allowed_values_for_slot(slot: Slot) -> Union[str, None]:
 
 
 def resolve_model_client_config(
-    model_config: Optional[Dict[str, Any]], component_name: Optional[str] = None
+    model_config: Optional[Dict[str, Any]],
+    component_name: Optional[str] = None,
+    model_groups: Optional[List[Dict[str, Any]]] = None,
 ) -> Optional[Dict[str, Any]]:
     """Resolve the model group in the model config.
 
@@ -835,6 +860,7 @@ def resolve_model_client_config(
         model_config: The model config to be resolved.
         component_name: The name of the component.
         component_name: The method of the component.
+        model_groups: Model groups from endpoints.yml.
 
     Returns:
         The resolved llm config.
@@ -861,7 +887,12 @@ def resolve_model_client_config(
 
     model_group_id = model_config.get(MODEL_GROUP_CONFIG_KEY)
 
-    endpoints = AvailableEndpoints.get_instance()
+    # If `model_groups` is provided, use it to initialise `AvailableEndpoints`,
+    # since `get_instance()` reads from the local endpoints file instead.
+    if model_groups:
+        endpoints = AvailableEndpoints(model_groups=model_groups)
+    else:
+        endpoints = AvailableEndpoints.get_instance()
     if endpoints.model_groups is None:
         _raise_invalid_config_exception(
             reason=(
@@ -919,3 +950,124 @@ async def create_tracker_for_user_step(
 
     # store the tracker with the unique sender id
     await agent.tracker_store.save(tracker)
+
+
+def check_prompt_config_keys_and_warn_if_deprecated(
+    config: dict, component_source: str
+) -> None:
+    """Checks and warns about deprecated config parameters."""
+    if PROMPT_CONFIG_KEY in config and PROMPT_TEMPLATE_CONFIG_KEY in config:
+        structlogger.warning(
+            f"{component_source}.init"
+            ".both_deprecated_and_non_deprecated_config_keys_used_at_the_same_time",
+            event_info=(
+                f"Both '{PROMPT_CONFIG_KEY}' and '{PROMPT_TEMPLATE_CONFIG_KEY}' "
+                f"are present in the config. '{PROMPT_CONFIG_KEY}' will be ignored "
+                f"in favor of {PROMPT_TEMPLATE_CONFIG_KEY}."
+            ),
+        )
+
+    # 'prompt' config key is deprecated in favor of 'prompt_template'
+    if PROMPT_CONFIG_KEY in config:
+        structlogger.warning(
+            f"{component_source}.init.deprecated_config_key",
+            event_info=(
+                f"The config parameter '{PROMPT_CONFIG_KEY}' is deprecated "
+                "and will be removed in Rasa 4.0.0. "
+                f"Please use the config parameter '{PROMPT_TEMPLATE_CONFIG_KEY}'"
+                f" instead. "
+            ),
+        )
+
+
+def _get_llm_command_generator_config(
+    config: Dict[Text, Any],
+) -> Optional[Dict[Text, Any]]:
+    """Get the llm command generator config from config.yml.
+
+    Args:
+        config: The config.yml file data.
+
+    Returns:
+        The llm command generator config.
+    """
+    from rasa.dialogue_understanding.generator import LLMBasedCommandGenerator
+
+    # Collect all LLM based Command Generator class names.
+    command_generator_subclasses = all_subclasses(LLMBasedCommandGenerator)
+    command_generator_class_names = [
+        command_generator.__name__ for command_generator in command_generator_subclasses
+    ]
+
+    # Read the LLM config of the Command Generator from the config.yml file.
+    pipelines = config.get(CONFIG_PIPELINE_KEY, [])
+    for pipeline in pipelines:
+        if pipeline.get(CONFIG_NAME_KEY) in command_generator_class_names:
+            return pipeline.get(LLM_CONFIG_KEY)
+
+    return None
+
+
+def _get_command_generator_prompt(
+    config: Dict[Text, Any], endpoints: Dict[Text, Any]
+) -> Text:
+    """Get the command generator prompt based on the config."""
+    from rasa.dialogue_understanding.generator.single_step.compact_llm_command_generator import (  # noqa: E501
+        DEFAULT_COMMAND_PROMPT_TEMPLATE_FILE_NAME,
+        FALLBACK_COMMAND_PROMPT_TEMPLATE_FILE_NAME,
+        MODEL_PROMPT_MAPPER,
+    )
+
+    model_config = _get_llm_command_generator_config(config)
+    llm_config = resolve_model_client_config(
+        model_config=model_config,
+        model_groups=endpoints.get(MODEL_GROUPS_CONFIG_KEY),
+    )
+    return get_default_prompt_template_based_on_model(
+        llm_config=llm_config,
+        model_prompt_mapping=MODEL_PROMPT_MAPPER,
+        default_prompt_path=DEFAULT_COMMAND_PROMPT_TEMPLATE_FILE_NAME,
+        fallback_prompt_path=FALLBACK_COMMAND_PROMPT_TEMPLATE_FILE_NAME,
+    )
+
+
+def _get_enterprise_search_prompt(config: Dict[Text, Any]) -> Text:
+    """Get the enterprise search prompt based on the config."""
+    from rasa.core.policies.enterprise_search_policy import EnterpriseSearchPolicy
+
+    def get_enterprise_search_config() -> Dict[Text, Any]:
+        policies = config.get(CONFIG_POLICIES_KEY, [])
+        for policy in policies:
+            if policy.get(CONFIG_NAME_KEY) == EnterpriseSearchPolicy.__name__:
+                return policy
+
+        return {}
+
+    enterprise_search_config = get_enterprise_search_config()
+    return EnterpriseSearchPolicy.get_system_default_prompt_based_on_config(
+        enterprise_search_config
+    )
+
+
+def get_system_default_prompts(
+    config: Dict[Text, Any], endpoints: Dict[Text, Any]
+) -> SystemPrompts:
+    """
+    Returns the system default prompts for the component.
+
+    Args:
+        config: The config.yml file data.
+        endpoints: The endpoints.yml file data.
+
+    Returns:
+        SystemPrompts: A Pydantic model containing all default prompts.
+    """
+    from rasa.core.nlg.contextual_response_rephraser import (
+        DEFAULT_RESPONSE_VARIATION_PROMPT_TEMPLATE,
+    )
+
+    return SystemPrompts(
+        command_generator=_get_command_generator_prompt(config, endpoints),
+        enterprise_search=_get_enterprise_search_prompt(config),
+        contextual_response_rephraser=DEFAULT_RESPONSE_VARIATION_PROMPT_TEMPLATE,
+    )

rasa/shared/utils/yaml.py

@@ -21,6 +21,7 @@ from ruamel.yaml import YAML, RoundTripRepresenter, YAMLError
 from ruamel.yaml.comments import CommentedMap, CommentedSeq
 from ruamel.yaml.constructor import BaseConstructor, DuplicateKeyError, ScalarNode
 from ruamel.yaml.loader import SafeLoader
+from ruamel.yaml.scalarstring import LiteralScalarString
 
 from rasa.shared.constants import (
     ASSERTIONS_SCHEMA_EXTENSIONS_FILE,
@@ -794,6 +795,25 @@ def write_yaml(
         should_preserve_key_order: Whether to force preserve key order in `data`.
         transform: A function to transform the data before writing it to the file.
     """
+
+    def multiline_str_representer(self: Any, value: str) -> Any:
+        """Dump multi-line strings as readable YAML block scalars where possible."""
+        if "\n" in value:
+            # First line after the newline decides: paragraph vs. snippet
+            first_line = value.split("\n", 1)[1]
+
+            # If the first line after the newline is not indented, treat the value
+            # as plain text. Indented text is likely pre-formatted YAML/JSON/etc.
+            if not first_line.startswith((" ", "\t")):
+                return self.represent_scalar(
+                    "tag:yaml.org,2002:str",
+                    LiteralScalarString(value),
+                    style="|",
+                )
+
+        # Fallback: keep default YAML scalar style (plain/quoted)
+        return self.represent_scalar("tag:yaml.org,2002:str", value)
+
     _enable_ordered_dict_yaml_dumping()
 
     if should_preserve_key_order:
@@ -808,6 +828,7 @@ def write_yaml(
         type(None),
         lambda self, _: self.represent_scalar("tag:yaml.org,2002:null", "null"),
     )
+    dumper.representer.add_representer(str, multiline_str_representer)
 
     if isinstance(target, StringIO):
         dumper.dump(data, target, transform=transform)
@@ -1025,6 +1046,17 @@ def validate_yaml_with_jsonschema(
     except (YAMLError, DuplicateKeyError) as e:
         raise YamlSyntaxException(underlying_yaml_exception=e)
 
+    validate_data_with_jsonschema(source_data, schema_content, humanize_error)
+
+
+def validate_data_with_jsonschema(
+    source_data: Any,
+    schema_content: Any,
+    humanize_error: Callable[
+        [jsonschema.ValidationError], str
+    ] = default_error_humanizer,
+) -> None:
+    """Validate Python object against the provided jsonschema content."""
     try:
         jsonschema.validate(source_data, schema_content)
     except jsonschema.ValidationError as error: