Flex flow, Prompty & Tracing examples

examples/flows/chat/chat-basic-code-first/README.md

@@ -0,0 +1,70 @@
+# Basic chat (code-first)
+This example shows how to create a basic chat flow using code-first approach. It demonstrates how to create a chatbot that can remember previous interactions and use the conversation history to generate next message.
+
+Tools used in this flow：
+- `llm` tool
+
+## Prerequisites
+
+Install promptflow sdk and other dependencies in this folder:
+```bash
+pip install -r requirements.txt
+```
+
+## What you will learn
+
+In this flow, you will learn
+- how to compose a chat flow.
+- prompt template format of LLM tool chat api. Message delimiter is a separate line containing role name and colon: "system:", "user:", "assistant:".
+See <a href="https://platform.openai.com/docs/api-reference/chat/create#chat/create-role" target="_blank">OpenAI Chat</a> for more about message role.
+    ```jinja
+    system:
+    You are a chatbot having a conversation with a human.
+
+    user:
+    {{question}}
+    ```
+- how to consume chat history in prompt.
+    ```jinja
+    {% for item in chat_history %}
+    user:
+    {{item.inputs.question}}
+    assistant:
+    {{item.outputs.answer}}
+    {% endfor %}
+    ```
+
+## Getting started
+
+### 1 Create connection for LLM tool to use
+Go to "Prompt flow" "Connections" tab. Click on "Create" button, select one of LLM tool supported connection types and fill in the configurations.
+
+Currently, there are two connection types supported by LLM tool: "AzureOpenAI" and "OpenAI". If you want to use "AzureOpenAI" connection type, you need to create an Azure OpenAI service first. Please refer to [Azure OpenAI Service](https://azure.microsoft.com/en-us/products/cognitive-services/openai-service/) for more details. If you want to use "OpenAI" connection type, you need to create an OpenAI account first. Please refer to [OpenAI](https://platform.openai.com/) for more details.
+
+```bash
+# Override keys with --set to avoid yaml file changes
+pf connection create --file ../../../connections/azure_openai.yml --set api_key=<your_api_key> api_base=<your_api_base> --name open_ai_connection
+```
+
+Note in [flow.dag.yaml](flow.dag.yaml) we are using connection named `open_ai_connection`.
+```bash
+# show registered connection 
+pf connection show --name open_ai_connection
+```
+
+### 2 Start chatting
+
+```bash
+# run chat flow with default question in flow.dag.yaml
+pf flow test --flow . 
+
+# run chat flow with new question
+pf flow test --flow . --inputs question="What's Azure Machine Learning?"
+
+# start a interactive chat session in CLI
+pf flow test --flow . --interactive
+
+# start a interactive chat session in CLI with verbose info
+pf flow test --flow . --interactive --verbose
+```
+

examples/flows/chat/chat-basic-code-first/chat.jinja2

@@ -0,0 +1,12 @@
+system:
+You are a helpful assistant.
+
+{% for item in chat_history %}
+user:
+{{item.inputs.question}}
+assistant:
+{{item.outputs.answer}}
+{% endfor %}
+
+user:
+{{question}}

examples/flows/chat/chat-basic-code-first/data.jsonl

@@ -0,0 +1,2 @@
+{"question": "What is Prompt flow?"}
+{"question": "What is ChatGPT?"}

examples/flows/chat/chat-basic-code-first/flow.dag.yaml

@@ -0,0 +1,3 @@
+$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
+path: flow.py
+entry: flow_entry

examples/flows/chat/chat-basic-code-first/flow.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass
+from jinja2 import Template
+from pathlib import Path
+from promptflow import trace, PFClient
+from promptflow.tools.aoai import chat
+
+
+BASE_DIR = Path(__file__).absolute().parent
+
+
+@trace
+def load_prompt(jinja2_template: str, question: str, chat_history: list) -> str:
+    """Load prompt function."""
+    with open(BASE_DIR / jinja2_template, "r", encoding="utf-8") as f:
+        tmpl = Template(f.read(), trim_blocks=True, keep_trailing_newline=True)
+        prompt = tmpl.render(question=question, chat_history=chat_history)
+        return prompt
+
+
+@dataclass
+class Result:
+    answer: str
+
+
+@trace
+def flow_entry(question: str='What is ChatGPT?', chat_history: list = []) -> Result:
+    """Flow entry function."""
+    from promptflow._sdk._configuration import Configuration
+
+    prompt = load_prompt("chat.jinja2", question, chat_history)
+    config = Configuration.get_instance()
+    # TODO: create your own config.json
+    workspace_config = config._get_workspace_from_config(path="./config.json")
+    config.set_config(
+        Configuration.CONNECTION_PROVIDER,
+        "azureml:" + workspace_config
+    )
+    pf = PFClient()
+    connection = pf.connections.get("open_ai_connection", with_secrets=True) # TODO: add connection to function inputs
+    output = chat(
+        connection=connection,
+        prompt=prompt,
+        deployment_name="gpt-35-turbo",
+        max_tokens=256,
+        temperature=0.7,
+    )
+    # TODO: Result(answer=output)
+    return dict(answer=output)
+
+
+if __name__ == "__main__":
+    result = flow_entry("What's Azure Machine Learning?", [])
+    print(result)

examples/flows/chat/chat-basic-code-first/requirements.txt

@@ -0,0 +1,2 @@
+--extra-index-url https://azuremlsdktestpypi.azureedge.net/test-promptflow/
+promptflow[azure]==0.0.116642424

examples/flows/standard/basic-code-first/.env.example

@@ -0,0 +1,3 @@
+AZURE_OPENAI_API_KEY=<your_AOAI_key>
+AZURE_OPENAI_API_BASE=<your_AOAI_endpoint>
+AZURE_OPENAI_API_TYPE=azure

examples/flows/standard/basic-code-first/README.md

@@ -0,0 +1,125 @@
+# Basic standard flow (code-first)
+A basic standard flow using code-first approach calls Azure OpenAI with connection info stored in environment variables. 
+
+## Prerequisites
+
+Install promptflow sdk and other dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Run flow
+
+- Prepare your Azure Open AI resource follow this [instruction](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal) and get your `api_key` if you don't have one.
+
+- Setup environment variables
+
+Ensure you have put your azure open ai endpoint key in [.env](.env) file. You can create one refer to this [example file](.env.example).
+
+```bash
+cat .env
+```
+
+- Test flow/node
+```bash
+# test with default input value in flow.dag.yaml
+pf flow test --flow .
+
+# test with flow inputs
+pf flow test --flow . --inputs text="Java Hello World!"
+
+```
+
+- Create run with multiple lines data
+```bash
+# using environment from .env file (loaded in user code: hello.py)
+pf run create --flow . --data ./data.jsonl --column-mapping text='${data.text}' --stream
+```
+
+You can also skip providing `column-mapping` if provided data has same column name as the flow.
+Reference [here](https://aka.ms/pf/column-mapping) for default behavior when `column-mapping` not provided in CLI.
+
+- List and show run meta
+```bash
+# list created run
+pf run list
+
+# get a sample run name
+
+name=$(pf run list -r 10 | jq '.[] | select(.name | contains("basic_code_first")) | .name'| head -n 1 | tr -d '"')
+# show specific run detail
+pf run show --name $name
+
+# show output
+pf run show-details --name $name
+
+# visualize run in browser
+pf run visualize --name $name
+```
+
+## Run flow with connection
+Storing connection info in .env with plaintext is not safe. We recommend to use `pf connection` to guard secrets like `api_key` from leak.
+
+- Show or create `open_ai_connection`
+```bash
+# create connection from `azure_openai.yml` file
+# Override keys with --set to avoid yaml file changes
+pf connection create --file ../../../connections/azure_openai.yml --set api_key=<your_api_key> api_base=<your_api_base>
+
+# check if connection exists
+pf connection show -n open_ai_connection
+```
+
+- Test using connection secret specified in environment variables
+**Note**: we used `'` to wrap value since it supports raw value without escape in powershell & bash. For windows command prompt, you may remove the `'` to avoid it become part of the value.
+
+```bash
+# test with default input value in flow.dag.yaml 
+pf flow test --flow . --environment-variables AZURE_OPENAI_API_KEY='${open_ai_connection.api_key}' AZURE_OPENAI_API_BASE='${open_ai_connection.api_base}'
+```
+
+- Create run using connection secret binding specified in environment variables, see [run.yml](run.yml)
+```bash
+# create run
+pf run create --flow . --data ./data.jsonl --stream --environment-variables AZURE_OPENAI_API_KEY='${open_ai_connection.api_key}' AZURE_OPENAI_API_BASE='${open_ai_connection.api_base}' --column-mapping text='${data.text}'
+# create run using yaml file
+pf run create --file run.yml --stream
+
+# show outputs
+name=$(pf run list -r 10 | jq '.[] | select(.name | contains("basic_variant_0")) | .name'| head -n 1 | tr -d '"')
+pf run show-details --name $name
+```
+
+## Run flow in cloud with connection
+- Assume we already have a connection named `open_ai_connection` in workspace.
+```bash
+# set default workspace
+az account set -s <your_subscription_id>
+az configure --defaults group=<your_resource_group_name> workspace=<your_workspace_name>
+```
+
+- Create run
+```bash
+# run with environment variable reference connection in azureml workspace 
+pfazure run create --flow . --data ./data.jsonl --environment-variables AZURE_OPENAI_API_KEY='${open_ai_connection.api_key}' AZURE_OPENAI_API_BASE='${open_ai_connection.api_base}' --column-mapping text='${data.text}' --stream --runtime example-runtime-ci
+# run using yaml file
+pfazure run create --file run.yml --stream --runtime example-runtime-ci
+```
+
+- List and show run meta
+```bash
+# list created run
+pfazure run list -r 3
+
+# get a sample run name
+name=$(pfazure run list -r 100 | jq '.[] | select(.name | contains("basic_code_first")) | .name'| head -n 1 | tr -d '"')
+
+# show specific run detail
+pfazure run show --name $name
+
+# show output
+pfazure run show-details --name $name
+
+# visualize run in browser
+pfazure run visualize --name $name
+```

examples/flows/standard/basic-code-first/data.jsonl

@@ -0,0 +1,3 @@
+{"text": "Python Hello World!"}
+{"text": "C Hello World!"}
+{"text": "C# Hello World!"}

examples/flows/standard/basic-code-first/flow.dag.yaml

@@ -0,0 +1,3 @@
+$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
+path: flow.py
+entry: flow_entry

examples/flows/standard/basic-code-first/flow.py

@@ -0,0 +1,32 @@
+from jinja2 import Template
+from pathlib import Path
+from promptflow import trace
+
+from hello import my_llm_tool
+
+BASE_DIR = Path(__file__).absolute().parent
+
+
+@trace
+def load_prompt(jinja2_template: str, text: str) -> str:
+    """Load prompt function."""
+    with open(BASE_DIR / jinja2_template, "r", encoding="utf-8") as f:
+        prompt = Template(
+            f.read(), trim_blocks=True, keep_trailing_newline=True
+        ).render(text=text)
+        return prompt
+
+
+@trace
+def flow_entry(text: str = "Hello World!") -> str:
+    """Flow entry function."""
+    prompt = load_prompt("hello.jinja2", text)
+    output = my_llm_tool(
+        prompt=prompt, deployment_name="text-davinci-003", max_tokens=120
+    )
+    return output
+
+
+if __name__ == "__main__":
+    result = flow_entry("Hello, world!")
+    print(result)

examples/flows/standard/basic-code-first/hello.jinja2

@@ -0,0 +1,2 @@
+{# Please replace the template with your own prompt. #}
+Write a simple {{text}} program that displays the greeting message when executed.