microsoft--promptflow/examples/connections/connection.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Connection Management\n",
    "\n",
    "Prompt flow provides various prebuilt connections, including Azure OpenAI, OpenAI, Azure Content Safety, etc. Prebuilt connections enable seamless integration with these resources within the built-in tools. \n",
    "\n",
    "Additionally, users have the flexibility to create custom connection types using key-value pairs, empowering them to tailor the connections to their specific requirements, particularly in Python tools.\n",
    "\n",
    "Reach more details about connection types [here](https://learn.microsoft.com/en-us/azure/machine-learning/prompt-flow/concept-connections?view=azureml-api-2).\n",
    "## Create different type of connections\n",
    "We will use Azure OpenAI connection and custom connection as example to show how to create connection with promptflow sdk."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Install dependent packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install -r ../requirements.txt"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Initialize a pf client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from promptflow.client import PFClient\n",
    "\n",
    "# client can help manage your runs and connections.\n",
    "client = PFClient()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create an Azure OpenAI connection\n",
    "\n",
    "Prepare your Azure OpenAI 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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from promptflow.entities import AzureOpenAIConnection\n",
    "\n",
    "# Initialize an AzureOpenAIConnection object\n",
    "connection = AzureOpenAIConnection(\n",
    "    name=\"my_azure_open_ai_connection\",\n",
    "    api_key=\"<your-api-key>\",\n",
    "    api_base=\"<your-endpoint>\",\n",
    ")\n",
    "# Create the connection, note that api_key will be scrubbed in the returned result\n",
    "result = client.connections.create_or_update(connection)\n",
    "print(result)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a custom connection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from promptflow.entities import CustomConnection\n",
    "\n",
    "# Initialize a custom connection object\n",
    "connection = CustomConnection(\n",
    "    name=\"my_custom_connection\",\n",
    "    # Secrets is a required field for custom connection\n",
    "    secrets={\"my_key\": \"<your-api-key>\"},\n",
    "    configs={\"endpoint\": \"<your-endpoint>\", \"other_config\": \"other_value\"},\n",
    ")\n",
    "# Create the connection, note that all secret values will be scrubbed in the returned result\n",
    "result = client.connections.create_or_update(connection)\n",
    "print(result)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## List all connections"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connections = client.connections.list()\n",
    "for connection in connections:\n",
    "    print(connection)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get a connection by name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connection = client.connections.get(name=\"my_custom_connection\")\n",
    "print(connection)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Delete a connection by name"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update a connection\n",
    "### Update an Azure OpenAI connection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connection = client.connections.get(name=\"my_azure_open_ai_connection\")\n",
    "connection.api_base = \"new_value\"\n",
    "connection.api_key = (\n",
    "    \"<original-key>\"  # secrets are required again when updating connection using sdk\n",
    ")\n",
    "result = client.connections.create_or_update(connection)\n",
    "print(connection)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update a custom connection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connection = client.connections.get(name=\"my_custom_connection\")\n",
    "connection.configs[\"other_config\"] = \"new_value\"\n",
    "connection.secrets[\n",
    "    \"my_key\"\n",
    "] = \"new_secret_value\"  # ValueError: Connection 'my_custom_connection' secrets ['my_key'] must be filled again when updating it.\n",
    "result = client.connections.create_or_update(connection)\n",
    "print(connection)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# client.connections.delete(name=\"my_custom_connection\")"
   ]
  }
 ],
 "metadata": {
  "description": "Manage various types of connections using sdk",
  "kernelspec": {
   "display_name": "promptflow-sdk",
   "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.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}