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

rasa/studio/download/flows.py

@@ -0,0 +1,351 @@
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Set, Text
+
+from rasa.shared.core.flows import Flow
+from rasa.shared.core.flows.flow_step_links import StaticFlowStepLink
+from rasa.shared.core.flows.flows_list import FlowsList
+from rasa.shared.core.flows.yaml_flows_io import YAMLFlowsReader, YamlFlowsWriter
+from rasa.shared.importers.importer import TrainingDataImporter
+from rasa.shared.utils.yaml import read_yaml
+from rasa.studio.constants import STUDIO_NLU_FILENAME
+from rasa.studio.data_handler import StudioDataHandler
+from rasa.utils.mapper import RasaPrimitiveStorageMapper
+
+logger = logging.getLogger(__name__)
+
+STUDIO_FLOWS_DIR_NAME = "studio_flows"
+
+
+def merge_flows_with_overwrite(
+    data_path: Path,
+    handler: Any,
+    data_from_studio: TrainingDataImporter,
+    data_local: TrainingDataImporter,
+    mapper: RasaPrimitiveStorageMapper,
+) -> None:
+    """
+    Merges flows data from a file or directory when overwrite is enabled.
+
+    Args:
+        data_path: List of paths to the training data.
+        handler: The StudioDataHandler instance.
+        data_from_studio: The TrainingDataImporter instance for Studio data.
+        data_local: The TrainingDataImporter instance for local data.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+    """
+    if data_path.is_file():
+        merge_training_data_file(handler, data_from_studio, data_local, data_path)
+    elif data_path.is_dir():
+        merge_training_data_dir(
+            handler, data_from_studio, data_local, data_path, mapper
+        )
+    else:
+        raise ValueError("Provided data path is neither a file nor a directory.")
+
+
+def merge_training_data_file(
+    handler: StudioDataHandler,
+    data_from_studio: TrainingDataImporter,
+    data_local: TrainingDataImporter,
+    file_path: Path,
+) -> None:
+    """
+    Merges NLU and flows data when training data is stored in a single file.
+
+    Args:
+        handler: The StudioDataHandler instance.
+        data_from_studio: The TrainingDataImporter instance for Studio data.
+        data_local: The TrainingDataImporter instance for local data.
+        file_path: The path to the training data file.
+    """
+    if handler.has_nlu():
+        nlu_data_merged = data_from_studio.get_nlu_data().merge(
+            data_local.get_nlu_data()
+        )
+        nlu_data_merged.persist_nlu(file_path)
+
+    if handler.has_flows():
+        flows_data_merged = data_from_studio.get_user_flows().merge(
+            data_local.get_user_flows()
+        )
+        YamlFlowsWriter.dump(
+            flows=flows_data_merged.underlying_flows,
+            filename=file_path,
+            should_clean_json=True,
+        )
+
+
+def merge_training_data_dir(
+    handler: StudioDataHandler,
+    data_from_studio: TrainingDataImporter,
+    data_local: TrainingDataImporter,
+    data_path: Path,
+    mapper: RasaPrimitiveStorageMapper,
+) -> None:
+    """
+    Merges NLU and flows data when training data is stored in a directory.
+
+    Args:
+        handler: The StudioDataHandler instance.
+        data_from_studio: The TrainingDataImporter instance for Studio data.
+        data_local: The TrainingDataImporter instance for local data.
+        data_path: The path to the training data directory.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+    """
+    if handler.has_nlu():
+        merge_nlu_in_directory(data_from_studio, data_local, data_path, mapper)
+
+    if handler.has_flows():
+        merge_flows_in_directory(data_from_studio, data_path, mapper)
+
+
+def merge_nlu_in_directory(
+    data_from_studio: TrainingDataImporter,
+    data_local: TrainingDataImporter,
+    data_path: Path,
+    mapper: RasaPrimitiveStorageMapper,
+) -> None:
+    """
+    Merges NLU data by checking for an existing NLU file in the directory.
+    If it exists, the new Studio data is merged with the local data.
+
+    Args:
+        data_from_studio: The TrainingDataImporter instance for Studio data.
+        data_local: The TrainingDataImporter instance for local data.
+        data_path: The path to the training data directory.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+    """
+    from rasa.studio.download.download import pretty_write_nlu_yaml
+
+    nlu_data = data_from_studio.get_nlu_data()
+    nlu_file_path = get_nlu_path(data_path, data_local, mapper)
+
+    if nlu_file_path.exists():
+        local_nlu = TrainingDataImporter.load_from_dict(
+            training_data_paths=[str(nlu_file_path)]
+        )
+        nlu_data = nlu_data.merge(local_nlu.get_nlu_data())
+
+    if nlu_yaml := nlu_data.nlu_as_yaml():
+        pretty_write_nlu_yaml(read_yaml(nlu_yaml), nlu_file_path)
+
+
+def get_nlu_path(
+    base_path: Path,
+    data_local: TrainingDataImporter,
+    mapper: RasaPrimitiveStorageMapper,
+) -> Path:
+    """Determines where NLU data should be stored.
+
+    Args:
+        base_path: The base path for the training data.
+        data_local: The TrainingDataImporter instance for local data.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+
+    Returns:
+        The path where NLU data should be stored.
+    """
+    nlu_paths = set()
+    for intent in data_local.get_nlu_data().intents:
+        for p in mapper.get_file(intent, "intents").get("training", []):
+            nlu_paths.add(p)
+
+    return _select_path(nlu_paths, "nlu", base_path, STUDIO_NLU_FILENAME)
+
+
+def get_flows_path(
+    base_path: Path,
+    data_local: TrainingDataImporter,
+    mapper: RasaPrimitiveStorageMapper,
+) -> Path:
+    """Determines where flows data should be stored.
+
+    Args:
+        base_path: The base path for the training data.
+        data_local: The TrainingDataImporter instance for local data.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+
+    Returns:
+        The path where flows data should be stored.
+    """
+    flow_paths = set()
+    for flow in data_local.get_user_flows().underlying_flows:
+        for p in mapper.get_file(flow.id, "flows").get("training", []):
+            flow_paths.add(p)
+
+    return _select_path(flow_paths, "flows", base_path, "flows.yml")
+
+
+def merge_flows_in_directory(
+    data_from_studio: TrainingDataImporter,
+    data_path: Path,
+    mapper: RasaPrimitiveStorageMapper,
+) -> None:
+    """
+    Merges flows data by updating local flow files in a directory with any changes
+    from Studio, and then dumping any new flows that do not exist in any local file.
+
+    Args:
+        data_from_studio: Training data importer containing the flows from Studio.
+        data_path: The path to the directory where local flows reside.
+        mapper: Utility for mapping flow IDs to their respective file paths.
+    """
+    # Extract flows from Studio data and map flow IDs to their instances.
+    studio_flows = data_from_studio.get_user_flows()
+    studio_flow_map: Dict[Text, Flow] = {
+        flow.id: flow for flow in studio_flows.underlying_flows
+    }
+
+    # Load existing local flows from the specified directory.
+    local_flows_file = TrainingDataImporter.load_from_dict(
+        training_data_paths=[str(data_path)]
+    )
+    local_flows = local_flows_file.get_user_flows().underlying_flows
+
+    # Gather the unique file paths where each local flow is stored.
+    local_flow_paths: Set[Path] = _get_local_flow_paths(local_flows, mapper)
+
+    # Track updated flows and update local files with Studio flow data.
+    all_updated_flows_ids: List[Text] = []
+    for flow_file_path in local_flow_paths:
+        updated_flows_ids = _update_flow_file(flow_file_path, studio_flow_map)
+        all_updated_flows_ids.extend(updated_flows_ids)
+
+    # Identify new Studio flows and save them as separate files in the directory.
+    new_flows = [
+        flow
+        for flow_id, flow in studio_flow_map.items()
+        if flow_id not in all_updated_flows_ids
+    ]
+    _dump_flows_as_separate_files(new_flows, data_path)
+
+
+def _get_local_flow_paths(
+    local_flows: List[Any],
+    mapper: RasaPrimitiveStorageMapper,
+) -> Set[Path]:
+    """
+    Args:
+        local_flows: List of local flows.
+        mapper: The RasaPrimitiveStorageMapper instance for mapping.
+
+    Returns:
+        A set of paths for the local flow files.
+    """
+    paths: Set[Path] = set()
+    for flow in local_flows:
+        paths.update(mapper.get_file(flow.id, "flows").get("training", []))
+    return paths
+
+
+def _update_flow_file(
+    flow_file_path: Path, studio_flows_map: Dict[Text, Any]
+) -> List[Text]:
+    """
+    Reads a flow file, updates outdated flows, and replaces them with studio versions.
+
+    Args:
+        flow_file_path: The path to the flow file.
+        studio_flows_map: A dictionary mapping flow IDs to their updated versions.
+
+    Returns:
+        A list of Flows IDs from the updated flow file.
+    """
+    file_flows = YAMLFlowsReader.read_from_file(flow_file_path, False)
+
+    # Build a list of flows, replacing any outdated flow with its studio version
+    updated_flows = [
+        studio_flows_map.get(flow.id, flow) or flow
+        for flow in file_flows.underlying_flows
+    ]
+
+    # If the updated flows differ from the original file flows, write them back
+    if updated_flows != file_flows.underlying_flows:
+        YamlFlowsWriter.dump(
+            flows=updated_flows,
+            filename=flow_file_path,
+            should_clean_json=True,
+        )
+
+    return [flow.id for flow in updated_flows]
+
+
+def _dump_flows_as_separate_files(flows: List[Any], data_path: Path) -> None:
+    """Dump flow into separate files within a directory.
+
+    Creates a new directory under the given data_path and writes each flow
+    into a separate YAML file. Each file is named after the flow's id.
+
+    Args:
+        flows: List of new flows to be dumped.
+        data_path: The path to the directory where the files will be created.
+    """
+    # If there are no flows, don't create a directory.
+    if not flows:
+        return
+
+    new_flows_dir = data_path / STUDIO_FLOWS_DIR_NAME
+    new_flows_dir.mkdir(parents=True, exist_ok=True)
+    for flow in flows:
+        file_name = f"{flow.id}.yml"
+        file_path = new_flows_dir / file_name
+        single_flow_list = FlowsList(underlying_flows=[flow])
+        YamlFlowsWriter.dump(
+            flows=single_flow_list.underlying_flows,
+            filename=file_path,
+            should_clean_json=True,
+        )
+
+
+def strip_default_next_references(flows: FlowsList) -> FlowsList:
+    """Strips default next references from flows.
+
+    Args:
+        flows: The FlowsList instance containing the flows.
+
+    Returns:
+        An updated FlowsList instance with default next references removed.
+    """
+    default_step_ids = [step.default_id for flow in flows for step in flow.steps]
+    for flow in flows:
+        for step in flow.steps:
+            if (
+                step.next.links
+                and isinstance(step.next.links[0], StaticFlowStepLink)
+                and step.next.links[0].target in default_step_ids
+            ):
+                step.next.links = []
+    return flows
+
+
+def _select_path(
+    paths: Set[Path], primitive_type: str, default_path: Path, default: str
+) -> Path:
+    """Selects a path from a set of paths.
+
+    If exactly one path exists, returns it.
+    If multiple exist, returns one with a warning.
+    If none exist, returns a default path.
+
+    Args:
+        paths: A set of paths.
+        primitive_type: The type of the primitive (e.g., "domain", "nlu").
+        default_path: The default path to use if no paths exist.
+        default: The default file name.
+
+    Returns:
+        The selected path.
+    """
+    if len(paths) == 1:
+        path = paths.pop()
+    elif len(paths) > 1:
+        path = paths.pop()
+        logger.warning(
+            f"Saving {primitive_type} to {path}. "
+            f"Please keep Studio-related {primitive_type} in a single file."
+        )
+    else:
+        path = default_path / Path(default)
+        logger.info(f"Saving {primitive_type} to {path}.")
+    return path

rasa/studio/link.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Text, Union
+
+import questionary
+import structlog
+from pydantic import BaseModel, Field
+
+import rasa.shared.utils.cli
+from rasa.constants import RASA_DIR_NAME
+from rasa.shared.utils.yaml import read_yaml_file, write_yaml
+from rasa.studio.config import StudioConfig
+from rasa.studio.upload import (
+    check_if_assistant_already_exists,
+    handle_upload,
+    is_auth_working,
+)
+
+structlogger = structlog.get_logger(__name__)
+
+_LINK_FILE_NAME: Text = "studio.yml"
+
+
+class AssistantLinkPayload(BaseModel):
+    assistant_name: Text
+    studio_url: Text
+    linked_at: Text = Field(
+        default_factory=lambda: datetime.datetime.utcnow().isoformat() + "Z"
+    )
+
+
+def _link_file(project_root: Path) -> Path:
+    """Return `<project-root>/.rasa/studio.yml`.
+
+    Args:
+        project_root: The path to the project root.
+
+    Returns:
+        The path to the link file.
+    """
+    return project_root / RASA_DIR_NAME / _LINK_FILE_NAME
+
+
+def _write_link_file(
+    project_root: Path, assistant_name: Text, studio_url: Text
+) -> None:
+    """Persist assistant information inside the project.
+
+    Args:
+        project_root: The path to the project root.
+        assistant_name: The name of the assistant.
+        studio_url: The URL of the Rasa Studio instance.
+    """
+    file_path = _link_file(project_root)
+    file_path.parent.mkdir(exist_ok=True, parents=True)
+
+    payload = AssistantLinkPayload(
+        assistant_name=assistant_name,
+        studio_url=studio_url,
+    )
+    write_yaml(payload.model_dump(), file_path)
+
+
+def _read_link_file(
+    project_root: Path = Path.cwd(),
+) -> Optional[Union[List[Any], Dict[Text, Any]]]:
+    """Reads the link configuration file.
+
+    Args:
+        project_root: The path to the project root.
+
+    Returns:
+        The assistant information if the file exists, otherwise None.
+    """
+    file_path = _link_file(project_root)
+    if not file_path.is_file():
+        return None
+
+    return read_yaml_file(file_path)
+
+
+def read_assistant_name(project_root: Path = Path.cwd()) -> Optional[Text]:
+    """Reads the assistant_name from the linked configuration file.
+
+    Args:
+        project_root: The path to the project root.
+
+    Returns:
+        The assistant name if the file exists, otherwise None.
+    """
+    linked = _read_link_file(project_root)
+    assistant_name = (
+        linked.get("assistant_name") if linked and isinstance(linked, dict) else None
+    )
+
+    if not assistant_name:
+        rasa.shared.utils.cli.print_error_and_exit(
+            "This project is not linked to any Rasa Studio assistant.\n"
+            "Run `rasa studio link <assistant-name>` first."
+        )
+
+    return assistant_name
+
+
+def get_studio_config() -> StudioConfig:
+    """Get the StudioConfig object or exit with an error message.
+
+    Returns:
+        A valid StudioConfig object.
+    """
+    config = StudioConfig.read_config()
+    if not config.is_valid():
+        rasa.shared.utils.cli.print_error_and_exit(
+            "Rasa Studio is not configured correctly. Run `rasa studio config` first."
+        )
+    if not is_auth_working(config.studio_url, not config.disable_verify):
+        rasa.shared.utils.cli.print_error_and_exit(
+            "Authentication invalid or expired. Please run `rasa studio login`."
+        )
+    return config
+
+
+def _ensure_assistant_exists(
+    assistant_name: Text,
+    studio_cfg: StudioConfig,
+    args: argparse.Namespace,
+) -> bool:
+    """Create the assistant on Studio if it does not yet exist.
+
+    Args:
+        assistant_name: The name the user provided on the CLI.
+        studio_cfg: The validated Studio configuration.
+        args: The original CLI args (needed for `handle_upload`).
+
+    Returns:
+        True if the assistant already exists or was created, False otherwise.
+    """
+    verify_ssl = not studio_cfg.disable_verify
+    assistant_already_exists = check_if_assistant_already_exists(
+        assistant_name, studio_cfg.studio_url, verify_ssl
+    )
+    if not assistant_already_exists:
+        should_create_assistant = questionary.confirm(
+            f"Assistant '{assistant_name}' was not found on Rasa Studio. "
+            f"Do you want to create it?"
+        ).ask()
+        if should_create_assistant:
+            # `handle_upload` expects the name to live in `args.assistant_name`
+            args.assistant_name = assistant_name
+            handle_upload(args)
+
+            rasa.shared.utils.cli.print_info(
+                f"Assistant {assistant_name} successfully created."
+            )
+        return should_create_assistant
+
+    return assistant_already_exists
+
+
+def handle_link(args: argparse.Namespace) -> None:
+    """Implementation of `rasa studio link <assistant-name>` CLI command.
+
+    Args:
+        args: The command line arguments.
+    """
+    assistant_name: Text = args.assistant_name[0]
+    studio_cfg = get_studio_config()
+    assistant_exists = _ensure_assistant_exists(assistant_name, studio_cfg, args)
+    if not assistant_exists:
+        rasa.shared.utils.cli.print_error_and_exit(
+            "Project has not been linked with Studio assistant."
+        )
+
+    project_root = Path.cwd()
+    link_file = _link_file(project_root)
+
+    if link_file.exists():
+        overwrite = questionary.confirm(
+            f"This project is already linked " f"(link file '{link_file}').\nOverwrite?"
+        ).ask()
+        if not overwrite:
+            rasa.shared.utils.cli.print_info(
+                "Existing link kept – nothing was changed."
+            )
+            sys.exit(0)
+
+    _write_link_file(project_root, assistant_name, studio_cfg.studio_url)
+
+    structlogger.info(
+        "studio.link.success",
+        event_info=f"Project linked to Studio assistant '{assistant_name}'.",
+        assistant_name=assistant_name,
+    )
+    rasa.shared.utils.cli.print_success(
+        f"Project successfully linked to assistant '{assistant_name}'."
+    )

rasa/studio/pull.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Text, Union
+
+import structlog
+
+import rasa.cli.utils
+import rasa.shared.utils.cli
+from rasa.shared.constants import DEFAULT_CONFIG_PATH, DEFAULT_ENDPOINTS_PATH
+from rasa.shared.utils.io import write_text_file
+from rasa.studio.data_handler import StudioDataHandler
+from rasa.studio.download.download import handle_download
+from rasa.studio.link import get_studio_config, read_assistant_name
+
+structlogger = structlog.get_logger(__name__)
+
+
+def _write_to_file(
+    content: Text, file_type: Text, file_path: Text, default_path: Text
+) -> None:
+    """Write the content to a file.
+
+    Args:
+        content: The content to write.
+        file_type: The type of file (e.g., "config" or "endpoints".).
+        file_path: The path to the file.
+        default_path: The default path to use file_path is not valid.
+    """
+    path: Union[Path, str, None] = rasa.cli.utils.get_validated_path(
+        file_path, file_type, default_path, none_is_valid=True
+    )
+    write_text_file(content, path, encoding="utf-8")
+    rasa.shared.utils.cli.print_success(f"Pulled {file_type} data from assistant.")
+
+
+def handle_pull(args: argparse.Namespace) -> None:
+    """Pull all data and overwrite the local assistant.
+
+    Args:
+        args: The parsed arguments.
+    """
+    assistant_name = read_assistant_name()
+
+    # Use the CLI command logic to download with overwrite
+    download_args = argparse.Namespace(**vars(args))
+    download_args.assistant_name = [assistant_name]
+    download_args.overwrite = True
+
+    handle_download(download_args)
+    rasa.shared.utils.cli.print_success("Pulled the data from assistant.")
+
+
+def handle_pull_config(args: argparse.Namespace) -> None:
+    """Pull just the assistant's `config.yml`.
+
+    Args:
+        args: The parsed arguments.
+    """
+    studio_cfg = get_studio_config()
+    assistant_name = read_assistant_name()
+
+    handler = StudioDataHandler(studio_cfg, assistant_name)
+    handler.request_all_data()
+
+    config_yaml = handler.get_config()
+    if not config_yaml:
+        rasa.shared.utils.cli.print_error_and_exit(
+            "No configuration data was found in the Studio assistant."
+        )
+
+    _write_to_file(config_yaml, "config", args.config, DEFAULT_CONFIG_PATH)
+
+
+def handle_pull_endpoints(args: argparse.Namespace) -> None:
+    """Pull just the assistant's `endpoints.yml`.
+
+    Args:
+        args: The parsed arguments.
+    """
+    studio_cfg = get_studio_config()
+    assistant_name = read_assistant_name()
+
+    handler = StudioDataHandler(studio_cfg, assistant_name)
+    handler.request_all_data()
+
+    endpoints_yaml = handler.get_endpoints()
+    if not endpoints_yaml:
+        rasa.shared.utils.cli.print_error_and_exit(
+            "No endpoints data was found in the Studio assistant."
+        )
+
+    _write_to_file(endpoints_yaml, "endpoints", args.endpoints, DEFAULT_ENDPOINTS_PATH)