Merge branch 'microsoft:main' into main

Author: ttthree

.github/workflows/build_doc_ci.yml

@@ -11,11 +11,11 @@ on:
       - 'docs/**'
       - 'scripts/docs/**'
       - '.github/workflows/build_doc_ci.yml'
+      - 'src/promptflow/promptflow/**'
 
 env:
   packageSetupType: promptflow_with_extra
   testWorkingDirectory: ${{ github.workspace }}/src/promptflow
-  condaEnvName: release-env
 
 jobs:
   build_doc_job:
@@ -27,10 +27,21 @@ jobs:
         with:
           submodules: true
 
-      - name: Build Doc
+      - name: Python Setup
+        uses: "./.github/actions/step_create_python_environment"
+
+      - name: Dev setup
+        uses: "./.github/actions/step_sdk_setup"
+        with:
+          setupType: ${{ env.packageSetupType }}
+          scriptPath: ${{ env.testWorkingDirectory }}
+
+      - name: Build doc with reference doc
         shell: powershell
         working-directory: scripts/docs/
-        run: ./doc_generation.ps1 -WarningAsError:$true
+        run: |-
+          pip install langchain
+          ./doc_generation.ps1 -WithReferenceDoc:$true -WarningAsError:$true 
 
   # Note: We have this job separately because some error may missing when build link check exists.
   link_check_job:
@@ -46,30 +57,3 @@ jobs:
         shell: powershell
         working-directory: scripts/docs/
         run: ./doc_generation.ps1 -BuildLinkCheck -WarningAsError:$true
-
-  # TODO: Once we fixed all warnings in reference doc job, delete this whole job and make job "build_doc_job" to run with "-WithReferenceDoc:$true"
-  build_doc_with_reference_doc_job:
-    runs-on: windows-latest
-    name: Build Doc with Reference Doc
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@v2
-        with:
-          submodules: true
-
-      - name: Conda Setup
-        uses: "./.github/actions/step_create_conda_environment"
-
-      - name: Dev setup
-        uses: "./.github/actions/step_sdk_setup"
-        with:
-          setupType: ${{ env.packageSetupType }}
-          scriptPath: ${{ env.testWorkingDirectory }}
-
-      - name: Build doc with reference doc
-        shell: powershell
-        working-directory: scripts/docs/
-        run: |-
-          conda activate ${{ env.condaEnvName }}
-          pip install langchain
-          ./doc_generation.ps1 -WithReferenceDoc:$true

.github/workflows/promptflow-executor-e2e-test.yml

@@ -65,12 +65,12 @@ jobs:
         az account show
         pip install langchain
         python scripts/building/run_coverage_tests.py `
-          -p ${{ github.workspace }}/src/promptflow/promptflow `
-          -t ${{ github.workspace }}/src/promptflow/tests/executor/e2etests `
+          -p ${{ env.testWorkingDirectory }}/promptflow `
+          -t ${{ env.testWorkingDirectory }}/tests/executor/e2etests `
           -l eastus `
           -m "all" `
           -n ${{ steps.cpu-cores.outputs.count }}`
-          --coverage-config ${{ github.workspace }}/src/promptflow/tests/executor/.coveragerc
+          --coverage-config ${{ env.testWorkingDirectory }}/tests/executor/.coveragerc
     - name: Upload Test Results
       if: always()
       uses: actions/upload-artifact@v3

.github/workflows/promptflow-executor-unit-test.yml

@@ -64,12 +64,12 @@ jobs:
         gci env:* | sort-object name
         az account show
         python scripts/building/run_coverage_tests.py `
-          -p ${{ github.workspace }}/src/promptflow/promptflow `
-          -t ${{ github.workspace }}/src/promptflow/tests/executor/unittests `
+          -p ${{ env.testWorkingDirectory }}/promptflow `
+          -t ${{ env.testWorkingDirectory }}/tests/executor/unittests `
           -l eastus `
           -m "all" `
           -n ${{ steps.cpu-cores.outputs.count }} `
-          --coverage-config ${{ github.workspace }}/src/promptflow/tests/executor/.coveragerc
+          --coverage-config ${{ env.testWorkingDirectory }}/tests/executor/.coveragerc
     - name: Upload Test Results
       if: always()
       uses: actions/upload-artifact@v3

.github/workflows/publish_doc.yml

@@ -36,8 +36,8 @@ jobs:
         with:
           submodules: true
 
-      - name: Conda Setup
-        uses: "./.github/actions/step_create_conda_environment"
+      - name: Python Setup
+        uses: "./.github/actions/step_create_python_environment"
 
       - name: Dev setup
         uses: "./.github/actions/step_sdk_setup"

.gitignore

@@ -45,6 +45,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+cov.xml
 *.cover
 *.py,cover
 .hypothesis/

README.md

@@ -3,6 +3,13 @@
 [![Python package](https://img.shields.io/pypi/v/promptflow)](https://pypi.org/project/promptflow/)
 [![Python](https://img.shields.io/pypi/pyversions/promptflow.svg?maxAge=2592000)](https://pypi.python.org/pypi/promptflow/) 
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/promptflow)](https://pypi.org/project/promptflow/)
+[![CLI](https://img.shields.io/badge/CLI-reference-blue)](https://microsoft.github.io/promptflow/reference/pf-command-reference.html)
+[![vsc extension](https://img.shields.io/visual-studio-marketplace/i/prompt-flow.prompt-flow?logo=Visual%20Studio&label=Extension%20)](https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow)
+
+[![Doc](https://img.shields.io/badge/Doc-online-green)](https://microsoft.github.io/promptflow/index.html)
+[![Issue](https://img.shields.io/github/issues/microsoft/promptflow)](https://github.com/microsoft/promptflow/issues/new/choose)
+[![Discussions](https://img.shields.io/github/discussions/microsoft/promptflow)](https://github.com/microsoft/promptflow/issues/new/choose)
+[![CONTRIBUTING](https://img.shields.io/badge/Contributing-8A2BE2)](https://github.com/microsoft/promptflow/blob/main/CONTRIBUTING.md)
 [![License: MIT](https://img.shields.io/github/license/microsoft/promptflow)](https://github.com/microsoft/promptflow/blob/main/LICENSE)
 
 > Welcome to join us to make Prompt flow better by
@@ -14,20 +21,93 @@
 
 With prompt flow, you will be able to:
 
-- Create executable workflows that link LLMs, prompts, Python code and other tools together.
-- Debug and iterate your flows, especially the interaction with LLMs with ease.
-- Evaluate your flow's quality and performance with larger datasets.
-- Integrate the testing and evaluation into your CI/CD system to ensure quality of your flow.
-- Deploy your flow to the serving platform you choose or integrate into your app's code base easily.
-- (Optional but highly recommended) Collaborate with your team by leveraging the cloud version of [Prompt flow in Azure AI](https://learn.microsoft.com/en-us/azure/machine-learning/prompt-flow/overview-what-is-prompt-flow?view=azureml-api-2).
+- **Create and iteratively develop flow**
+    - Create executable [flows](https://microsoft.github.io/promptflow/concepts/concept-flows.html) that link LLMs, prompts, Python code and other [tools](https://microsoft.github.io/promptflow/concepts/concept-tools.html) together.
+    - Debug and iterate your flows, especially the [interaction with LLMs](https://microsoft.github.io/promptflow/concepts/concept-connections.html) with ease.
+- **Evaluate flow quality and performance**
+    - Evaluate your flow's quality and performance with larger datasets.
+    - Integrate the testing and evaluation into your CI/CD system to ensure quality of your flow.
+- **Streamlined development cycle for production**
+    - Deploy your flow to the serving platform you choose or integrate into your app's code base easily.
+    - (Optional but highly recommended) Collaborate with your team by leveraging the cloud version of [Prompt flow in Azure AI](https://learn.microsoft.com/en-us/azure/machine-learning/prompt-flow/overview-what-is-prompt-flow?view=azureml-api-2).
+
+------
+
+## Installation
+
+Ensure you have a python environment, `python=3.9` is recommended.
+
+```sh
+pip install promptflow promptflow-tools
+```
+
+## Quick Start ⚡
+
+**Create a chatbot with prompt flow**
+
+Run the command to initiate a prompt flow from a chat template, it creates folder named `my_chatbot` and generates required files within it:
+
+```sh
+pf flow init --flow ./my_chatbot --type chat
+```
+
+**Setup a connection for your API key**
+
+For OpenAI key, establish a connection by running the command, using the `openai.yaml` file in the `my_chatbot` folder, which stores your OpenAI key:
+
+```sh
+# Override keys with --set to avoid yaml file changes
+pf connection create --file ./my_chatbot/openai.yaml --set api_key=<your_api_key> --name open_ai_connection
+```
+
+For Azure OpenAI key, establish the connection by running the command, using the `azure_openai.yaml` file:
+
+```sh
+pf connection create --file ./my_chatbot/azure_openai.yaml --set api_key=<your_api_key> api_base=<your_api_base> --name open_ai_connection
+```
+
+**Chat with your flow**
+
+In the `my_chatbot` folder, there's a `flow.dag.yaml` file that outlines the flow, including inputs/outputs, nodes,  connection, and the LLM model, etc
+
+> Note that in the `chat` node, we're using a connection named `open_ai_connection` (specified in `connection` field) and the `gpt-35-turbo` model (specified in `deployment_name` field). The deployment_name filed is to specify the OpenAI model, or the Azure OpenAI deployment resource.
+
+Interact with your chatbot by running: (press `Ctrl + C` to end the session)
+
+```sh
+pf flow test --flow ./my_chatbot --interactive
+```
+
+Next Step! Continue with the **Tutorial**  👇 section to delve deeper into Prompt flow.
+
+## Tutorial 🏃‍♂️
+
+Prompt Flow is a tool designed to **build high quality LLM apps**, the development process in prompt flow follows these steps: develop a flow, improve the flow quality, deploy the flow to production.
+
+### Develop your own LLM apps
+
+#### VS Code Extension<img src="examples/tutorials/quick-start/media/logo_pf.png" alt="logo" width="25"/> 
+
+We also offer a VS Code extension (a flow designer) for an interactive flow development experience with UI. 
+
+<img src="examples/tutorials/quick-start/media/vsc.png" alt="vsc" width="1000"/>
+
+You can install it from the <a href="https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow">visualstudio marketplace</a>.
+
+#### Deep dive into flow development
+
+[Getting Started with Prompt Flow](https://microsoft.github.io/promptflow/how-to-guides/quick-start.html): A step by step guidance to invoke your first flow run.
+
+### Learn from use cases
+
+[Tutorial: Chat with PDF](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/e2e-development/chat-with-pdf.md): An end-to-end tutorial on how to build a high quality chat application with prompt flow, including flow development and evaluation with metrics.
+> More examples can be found [here](https://microsoft.github.io/promptflow/tutorials/index.html#samples). We welcome contributions of new use cases!
 
-## Get Started with Prompt flow ⚡
+### Setup for contributors
 
-Develop your LLM apps with Prompt flow: please start with our [docs](https://microsoft.github.io/promptflow/) & [examples](./examples/README.md):
-- [Getting Started with Prompt Flow](https://microsoft.github.io/promptflow/how-to-guides/quick-start.html): A step by step guidance to invoke your first flow run.
-- [Tutorial: Chat with PDF](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/e2e-development/chat-with-pdf.md): An end-to-end tutorial on how to build a high quality chat application with prompt flow, including flow development and evaluation with metrics.
+If you're interested in contributing, please start with our dev setup guide: [dev_setup.md](./docs/dev/dev_setup.md).
 
-Contribute to Prompt flow: please start with our dev setup guide: [dev_setup.md](./docs/dev/dev_setup.md).
+Next Step! Continue with the **Contributing**  👇 section to to contribute to Prompt flow.
 
 ## Contributing
 

docs/cloud/azureai/deploy-to-azure-appservice.md

@@ -10,7 +10,7 @@ This example demos how to deploy [web-classification](https://github.com/microso
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source ../../flows/standard/web-classification --output build --format docker
+pf flow build --source ../../flows/standard/web-classification --output dist --format docker
 ```
 
 Note that all dependent connections must be created before building as docker.
@@ -27,7 +27,7 @@ The two scripts will do the following things:
 :::{tab-item} Bash
 Example command to use bash script:
 ```shell
-bash deploy.sh --path build -i <image_tag> --name my_app_23d8m -r <docker registery> -g <resource_group>
+bash deploy.sh --path dist -i <image_tag> --name my_app_23d8m -r <docker registery> -g <resource_group>
 ```
 See the full parameters by `bash deploy.sh -h`.
 :::

docs/how-to-guides/deploy-a-flow/deploy-using-docker.md

@@ -53,7 +53,7 @@ refer to [Setup connection for web-classifiction](https://github.com/microsoft/p
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source ../../flows/standard/web-classification --output build --format docker
+pf flow build --source ../../flows/standard/web-classification --output dist --format docker
 ```
 
 Note that all dependent connections must be created before exporting as docker.
@@ -65,7 +65,7 @@ Like other Dockerfile, you need to build the image first. You can tag the image
 Run the command below to build image:
 
 ```bash
-docker build build -t web-classification-serve
+docker build dist -t web-classification-serve
 ```
 
 ### Run Docker image

examples/tutorials/e2e-development/chat-with-pdf.md

@@ -325,7 +325,7 @@ the other choices, please refer to [flow deploy docs](https://microsoft.github.i
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source . --output build --format docker
+pf flow build --source . --output dist --format docker
 ```
 
 ### Deploy with Docker
@@ -336,7 +336,7 @@ Like other Dockerfile, you need to build the image first. You can tag the image
 Run the command below to build image:
 
 ```shell
-docker build build -t chat-with-pdf-serve
+docker build dist -t chat-with-pdf-serve
 ```
 
 #### Run Docker image

examples/tutorials/flow-deploy/azure-app-service/README.md

@@ -18,7 +18,7 @@ pf connection create --file ../../../connections/azure_openai.yml --set api_key=
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source ../../../flows/standard/web-classification --output build --format docker
+pf flow build --source ../../../flows/standard/web-classification --output dist --format docker
 ```
 
 
@@ -32,7 +32,7 @@ The two scripts will do the following things:
 
 Example command to use bash script:
 ```shell
-bash deploy.sh --path build -i <image_tag> --name my_app_23d8m -r <docker registery> -g <resource_group>
+bash deploy.sh --path dist -i <image_tag> --name my_app_23d8m -r <docker registery> -g <resource_group>
 ```
 
 Example command to use powershell script:

examples/tutorials/flow-deploy/docker/README.md

@@ -14,7 +14,7 @@ pf connection create --file ../../../connections/azure_openai.yml --set api_key=
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source ../../../flows/standard/web-classification --output build --format docker
+pf flow build --source ../../../flows/standard/web-classification --output dist --format docker
 ```
 
 ## Deploy with Docker
@@ -25,7 +25,7 @@ Like other Dockerfile, you need to build the image first. You can tag the image
 Run the command below to build image:
 
 ```shell
-docker build build -t web-classification-serve
+docker build dist -t web-classification-serve
 ```
 
 ### Run Docker image

examples/tutorials/flow-deploy/kubernetes/README.md

@@ -15,7 +15,7 @@ pf connection create --file ../../../connections/azure_openai.yml --set api_key=
 Use the command below to build a flow as docker format app:
 
 ```bash
-pf flow build --source ../../../flows/standard/web-classification --output build --format docker
+pf flow build --source ../../../flows/standard/web-classification --output dist --format docker
 ```
 
 ## Deploy with Kubernetes
@@ -26,7 +26,7 @@ Like other Dockerfile, you need to build the image first. You can tag the image
 Then run the command below:
 
 ```shell
-cd build
+cd dist
 docker build . -t web-classification-serve
 ```
 

examples/tutorials/quick-start/media/logo_pf.png

@@ -21,7 +21,6 @@
     "sphinx_design",
     "sphinx_copybutton",
     "matplotlib.sphinxext.plot_directive",
-    "numpydoc",
     "sphinx_togglebutton",
     'myst_parser',
     "sphinx.builders.linkcheck",

examples/tutorials/quick-start/media/vsc.png

@@ -23,7 +23,7 @@ param(
 [string] $OutPath = [System.IO.Path]::Combine($ScriptPath, "_build")
 [string] $SphinxApiDoc = [System.IO.Path]::Combine($DocPath, "sphinx_apidoc.log")
 [string] $SphinxBuildDoc = [System.IO.Path]::Combine($DocPath, "sphinx_build.log")
-[string] $WarningErrorPattern = "WARNING:|ERROR:"
+[string] $WarningErrorPattern = "WARNING:|ERROR:|CRITICAL:"
 $apidocWarningsAndErrors = $null
 $buildWarningsAndErrors = $null
 
@@ -72,6 +72,13 @@ if($WithReferenceDoc){
     Write-Host "===============Build Promptflow Reference Doc==============="
     sphinx-apidoc --module-first --no-headings --no-toc --implicit-namespaces "$PkgSrcPath" -o "$RefDocPath" | Tee-Object -FilePath $SphinxApiDoc 
     $apidocWarningsAndErrors = Select-String -Path $SphinxApiDoc -Pattern $WarningErrorPattern
+
+    Write-Host "=============== Overwrite promptflow.connections.rst ==============="
+    # We are doing this overwrite because the connection entities are also defined in the promptflow.entities module
+    # and it will raise duplicate object description error if we don't do so when we run sphinx-build later.
+    $ConnectionRst = [System.IO.Path]::Combine($RepoRootPath, "scripts\docs\promptflow.connections.rst")
+    $AutoGenConnectionRst = [System.IO.Path]::Combine($RefDocPath, "promptflow.connections.rst")
+    Copy-Item -Path $ConnectionRst -Destination $AutoGenConnectionRst -Force
 }