microsoft--promptflow/examples/flows/integrations/unify-ai/flex-flow-quickstart-unify-ai.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with flex flow using Unify AI"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "**Learning Objectives** - Upon completing this tutorial, you should be able to:\n",
    "\n",
    "- Write LLM application using Unify AI API in notebook and visualize the trace of your application.\n",
    "- Choose a model/provider from [Unify model catalogue](https://unify.ai/benchmarks) for your flex flow.\n",
    "- Convert the application into a flow and batch run against multi lines of data.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0. Install dependent packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%capture --no-stderr\n",
    "%pip install -r ./requirements.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Trace your application with promptflow\n",
    "\n",
    "Assume we already have a python function that calls Unify AI. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"llm.py\") as fin:\n",
    "    print(fin.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: before running below cell, please configure required environment variable `UNIFY_AI_API_KEY` by create an `.env` file. Please refer to `./.env.example` as an template."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Choose LLM model and provider\n",
    "\n",
    "Define provider and model from Unify AI. Refer to [Unify model catalogue](https://unify.ai/benchmarks)\n",
    "\n",
    "Choose an optimal model/provider combination for your usecase by comparing trade-offs between quality, cost and latency. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# model_name and provider_name defined here are used throughout the notebook.\n",
    "# This example use llama 3.1 8b params and together-ai, redefine as per your usecase.\n",
    "\n",
    "model_name = \"llama-3.1-8b-chat\"\n",
    "provider_name = \"together-ai\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "from llm import my_llm_tool\n",
    "\n",
    "# pls configure `UNIFY_AI_API_KEY` environment variable\n",
    "result = my_llm_tool(\n",
    "    prompt=\"Write a simple Hello, world! python program that displays the greeting message when executed. Output code only.\",\n",
    "    model_name=model_name,\n",
    "    provider_name=provider_name,\n",
    ")\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualize trace by using start_trace\n",
    "\n",
    "Note we add `@trace` in the `my_llm_tool` function, re-run below cell will collect a trace in trace UI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from promptflow.tracing import start_trace\n",
    "\n",
    "# start a trace session, and print a url for user to check trace\n",
    "start_trace()\n",
    "# rerun the function, which will be recorded in the trace\n",
    "result = my_llm_tool(\n",
    "    prompt=\"Write a simple Hello, world! program that displays the greeting message when executed. Output code only.\",\n",
    "    model_name=model_name,\n",
    "    provider_name=provider_name,\n",
    ")\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's add another layer of function call. In `programmer.py` there is a function called `write_simple_program`, which calls a new function called `load_prompt` and previous `my_llm_tool` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# show the programmer.py content\n",
    "with open(\"programmer.py\") as fin:\n",
    "    print(fin.read())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# call the flow entry function\n",
    "from programmer import write_simple_program\n",
    "\n",
    "result = write_simple_program(\"Java Hello, world!\")\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setup model configuration with environment variables\n",
    "\n",
    "When used in local, create a model configuration object with environment variables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: before running below cell, please configure required environment variable `UNIFY_AI_API_KEY` and `UNIFY_AI_BASE_URL` by creating a `.env` file. Please refer to `./.env.example` as an template.\n",
    "\n",
    "Here OpenAI client is being used to call Unify AI API. `UNIFY_AI_BASE_URL` is the base url for the API endpoint (along with version) in [Unify API Documentation](https://unify.ai/docs/concepts/unify_api.html). `./.env.example` contains base url for for Unify API version v0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from dotenv import load_dotenv\n",
    "\n",
    "from promptflow.core import OpenAIModelConfiguration\n",
    "\n",
    "# pls configure `UNIFY_AI_API_KEY`, `UNIFY_AI_BASE_URL` environment variables first\n",
    "if \"UNIFY_AI_API_KEY\" not in os.environ:\n",
    "    # load environment variables from .env file\n",
    "    load_dotenv()\n",
    "\n",
    "if \"UNIFY_AI_API_KEY\" not in os.environ:\n",
    "    raise Exception(\"Please specify environment variables: UNIFY_AI_API_KEY\")\n",
    "model_config = OpenAIModelConfiguration(\n",
    "    base_url=os.environ[\"UNIFY_AI_BASE_URL\"],\n",
    "    api_key=os.environ[\"UNIFY_AI_API_KEY\"],\n",
    "    model=f\"{model_name}@{provider_name}\" \n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Eval the result "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "from eval_code_flow.code_quality_unify_ai import CodeEvaluator\n",
    "\n",
    "\n",
    "evaluator = CodeEvaluator(model_config=model_config)\n",
    "eval_result = evaluator(result)\n",
    "eval_result\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Batch run the function as flow with multi-line data\n",
    "\n",
    "Create a [flow.flex.yaml](https://github.com/microsoft/promptflow/blob/main/examples/flex-flows/basic/flow.flex.yaml) file to define a flow which entry pointing to the python function we defined.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# show the flow.flex.yaml content\n",
    "with open(\"flow.flex.yaml\") as fin:\n",
    "    print(fin.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Batch run with a data file (with multiple lines of test data)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from promptflow.client import PFClient\n",
    "\n",
    "pf = PFClient()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = \"./data.jsonl\"  # path to the data file\n",
    "# create run with the flow function and data\n",
    "base_run = pf.run(\n",
    "    flow=write_simple_program,\n",
    "    data=data,\n",
    "    column_mapping={\n",
    "        \"text\": \"${data.text}\",\n",
    "    },\n",
    "    stream=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "details = pf.get_details(base_run)\n",
    "details.head(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Evaluate your flow\n",
    "Then you can use an evaluation method to evaluate your flow. The evaluation methods are also flows which usually using LLM assert the produced output matches certain expectation. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run evaluation on the previous batch run\n",
    "The **base_run** is the batch run we completed in step 2 above, for web-classification flow with \"data.jsonl\" as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# we can also run flow pointing to code evaluator yaml file\n",
    "eval_flow = \"./eval_code_flow/code-eval-flow.flex.yaml\"\n",
    "\n",
    "eval_run = pf.run(\n",
    "    flow=eval_flow,\n",
    "    init={\"model_config\": model_config},\n",
    "    data=\"./data.jsonl\",  # path to the data file\n",
    "    run=base_run,  # specify base_run as the run you want to evaluate\n",
    "    column_mapping={\n",
    "        \"code\": \"${run.outputs.output}\",\n",
    "    },\n",
    "    stream=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "details = pf.get_details(eval_run)\n",
    "details.head(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "\n",
    "metrics = pf.get_metrics(eval_run)\n",
    "print(json.dumps(metrics, indent=4))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pf.visualize([base_run, eval_run])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## End Note\n",
    "\n",
    "By now you've successfully run your simple code generation and evaluation using Unify AI."
   ]
  }
 ],
 "metadata": {
  "build_doc": {
   "author": [
    "riddhijivani122@gmail.com"
   ],
   "category": "local",
   "section": "Flow",
   "weight": 10
  },
  "description": "A quickstart tutorial to run a flex flow and evaluate it.",
  "kernelspec": {
   "display_name": "prompt_flow",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.19"
  },
  "resources": "examples/requirements.txt, examples/flex-flows/basic"
 },
 "nbformat": 4,
 "nbformat_minor": 2
}