[SDK/CLI] Add pfazure download run feature. (#1378)

# Description


![image](https://github.com/microsoft/promptflow/assets/2572521/1f1f2cdf-6b2f-4706-aa42-114a0249afdd)


![image](https://github.com/microsoft/promptflow/assets/2572521/b016e614-b8c9-4404-ae4f-fbc8659c0a2c)


# All Promptflow Contribution checklist:
- [ ] **The pull request does not introduce [breaking changes].**
- [ ] **CHANGELOG is updated for new features, bug fixes or other
significant changes.**
- [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).**
- [ ] **Create an issue and link to the pull request to get dedicated
review from promptflow team. Learn more: [suggested
workflow](../CONTRIBUTING.md#suggested-workflow).**

## General Guidelines and Best Practices
- [ ] Title of the pull request is clear and informative.
- [ ] There are a small number of commits, each of which have an
informative message. This means that previously merged commits do not
appear in the history of the PR. For more information on cleaning up the
commits in your PR, [see this
page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md).

### Testing Guidelines
- [ ] Pull request includes test coverage for the included changes.

src/promptflow/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 1.2.0 (upcoming)
 
+### Features Added
+- [SDK/CLI] Support `pfazure run download` to download run data from Azure AI.
+
 ### Bugs Fixed
 
 - [SDK/CLI] Removing telemetry warning when running commands.

src/promptflow/promptflow/_cli/_params.py

@@ -56,20 +56,20 @@ def add_param_ua(parser):
 
 
 def add_param_flow_display_name(parser):
-    parser.add_argument("--flow", type=str, required=True, help="the flow name to create.")
+    parser.add_argument("--flow", type=str, required=True, help="The flow name to create.")
 
 
 def add_param_entry(parser):
-    parser.add_argument("--entry", type=str, help="the entry file.")
+    parser.add_argument("--entry", type=str, help="The entry file.")
 
 
 def add_param_function(parser):
-    parser.add_argument("--function", type=str, help="the function name in entry file.")
+    parser.add_argument("--function", type=str, help="The function name in entry file.")
 
 
 def add_param_prompt_template(parser):
     parser.add_argument(
-        "--prompt-template", action=AppendToDictAction, help="the prompt template parameter and assignment.", nargs="+"
+        "--prompt-template", action=AppendToDictAction, help="The prompt template parameter and assignment.", nargs="+"
     )
 
 
@@ -146,58 +146,30 @@ def add_param_inputs(parser):
     )
 
 
-def add_param_input(parser):
-    parser.add_argument(
-        "--input", type=str, required=True, help="the input file path. Note that we accept jsonl file only for now."
-    )
-
-
 def add_param_env(parser):
     parser.add_argument(
         "--env",
         type=str,
         default=None,
-        help="the dotenv file path containing the environment variables to be used in the flow.",
+        help="The dotenv file path containing the environment variables to be used in the flow.",
     )
 
 
 def add_param_output(parser):
-    parser.add_argument("--output", type=str, default="outputs", help="the output directory to store the results.")
-
-
-def add_param_flow(parser):
-    parser.add_argument("--flow", type=str, required=True, help="the evaluation flow to be used.")
-
-
-def add_param_source(parser):
-    parser.add_argument("--source", type=str, required=True, help="The flow or run source to be used.")
-
-
-def add_param_bulk_run_output(parser):
-    parser.add_argument("--bulk-run-output", type=str, help="the output directory of the bulk run.")
-
-
-def add_param_eval_output(parser):
-    parser.add_argument("--eval-output", type=str, help="the output file path of the evaluation result.")
-
-
-def add_param_column_mapping(parser):
     parser.add_argument(
-        "--column-mapping", type=str, required=True, help="the column mapping to be used in the evaluation."
+        "-o",
+        "--output",
+        type=str,
+        help="The output directory to store the results. Default to be current working directory if not specified.",
     )
 
 
-def add_param_runtime(parser):
-    parser.add_argument(
-        "--runtime",
-        type=str,
-        default="local",
-        help="Name of your runtime in Azure ML workspace, will run in cloud when runtime is not none.",
-    )
+def add_param_overwrite(parser):
+    parser.add_argument("--overwrite", action="store_true", help="Overwrite the existing results.")
 
 
-def add_param_connection(parser):
-    parser.add_argument("--connection", type=str, help="Name of your connection in Azure ML workspace.")
+def add_param_source(parser):
+    parser.add_argument("--source", type=str, required=True, help="The flow or run source to be used.")
 
 
 def add_param_run_name(parser):
@@ -208,16 +180,6 @@ def add_param_connection_name(parser):
     parser.add_argument("-n", "--name", type=str, help="Name of the connection to create.")
 
 
-def add_param_variants(parser):
-    parser.add_argument(
-        "--variants",
-        type=str,
-        nargs="+",
-        help="the variant run ids to be used in the evaluation. Note that we only support one variant for now.",
-        default=[],
-    )
-
-
 def add_param_max_results(parser):
     parser.add_argument(  # noqa: E731
         "-r",

src/promptflow/promptflow/_cli/_pf_azure/_run.py

@@ -13,7 +13,9 @@
     add_param_debug,
     add_param_include_archived,
     add_param_max_results,
+    add_param_output,
     add_param_output_format,
+    add_param_overwrite,
     add_param_run_name,
     add_param_set,
     add_param_verbose,
@@ -52,6 +54,7 @@ def add_parser_run(subparsers):
     add_parser_run_archive(subparsers)
     add_parser_run_restore(subparsers)
     add_parser_run_update(subparsers)
+    add_parser_run_download(subparsers)
     run_parser.set_defaults(action="run")
 
 
@@ -334,7 +337,7 @@ def add_parser_run_update(subparsers):
 Example:
 
 # Update a run metadata:
-pf run update --name <name> --set display_name="<display-name>" description="<description>" tags.key="<value>"
+pfazure run update --name <name> --set display_name="<display-name>" description="<description>" tags.key="<value>"
 """
     add_params = [
         _set_workspace_argument_for_subparsers,
@@ -353,6 +356,32 @@ def add_parser_run_update(subparsers):
     )
 
 
+def add_parser_run_download(subparsers):
+    """Add run download parser to the pfazure subparsers."""
+    epilog = """
+Example:
+
+# Download a run data to local:
+pfazure run download --name <name> --output <output-folder-path>
+"""
+    add_params = [
+        add_param_run_name,
+        add_param_output,
+        add_param_overwrite,
+        _set_workspace_argument_for_subparsers,
+    ] + base_params
+
+    activate_action(
+        name="download",
+        description="A CLI tool to download a run.",
+        epilog=epilog,
+        add_params=add_params,
+        subparsers=subparsers,
+        help_message="Download a run.",
+        action_param_name="sub_action",
+    )
+
+
 def dispatch_run_commands(args: argparse.Namespace):
     if args.sub_action == "create":
         pf = _get_azure_pf_client(args.subscription, args.resource_group, args.workspace_name, debug=args.debug)
@@ -403,6 +432,8 @@ def dispatch_run_commands(args: argparse.Namespace):
         restore_run(args.subscription, args.resource_group, args.workspace_name, args.name)
     elif args.sub_action == "update":
         update_run(args.subscription, args.resource_group, args.workspace_name, args.name, params=args.params_override)
+    elif args.sub_action == "download":
+        download_run(args)
 
 
 @exception_handler("List runs")
@@ -530,3 +561,9 @@ def update_run(
     pf = _get_azure_pf_client(subscription_id, resource_group, workspace_name)
     run = pf.runs.update(run=run_name, display_name=display_name, description=description, tags=tags)
     print(json.dumps(run._to_dict(), indent=4))
+
+
+@exception_handler("Download run")
+def download_run(args: argparse.Namespace):
+    pf = _get_azure_pf_client(args.subscription, args.resource_group, args.workspace_name, debug=args.debug)
+    pf.runs.download(run=args.name, output=args.output, overwrite=args.overwrite)

src/promptflow/promptflow/_sdk/_constants.py

@@ -18,6 +18,7 @@
 FLOW_TOOLS_JSON = "flow.tools.json"
 FLOW_TOOLS_JSON_GEN_TIMEOUT = 60
 PROMPT_FLOW_DIR_NAME = ".promptflow"
+PROMPT_FLOW_RUNS_DIR_NAME = ".runs"
 HOME_PROMPT_FLOW_DIR = (Path.home() / PROMPT_FLOW_DIR_NAME).resolve()
 SERVICE_CONFIG_FILE = "pf.yaml"
 PF_SERVICE_PORT_FILE = "pfs.port"

src/promptflow/promptflow/_sdk/_errors.py

@@ -92,6 +92,12 @@ class RunOperationParameterError(PromptflowException):
     pass
 
 
+class RunOperationError(PromptflowException):
+    """Exception raised when run operation failed."""
+
+    pass
+
+
 class FlowOperationError(PromptflowException):
     """Exception raised when flow operation failed."""