sdk/python/foundation-models/cohere/rerank-webrequests.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HTTP Requests API Usage in CLI\n",
    "\n",
    "\n",
    "\n",
    "## Basics\n",
    "For using the REST API, You will need to have a Endpoint url and Authentication Key associated with that endpoint.\n",
    "This can be acquired by following the deployment steps for AI Studio.\n",
    "\n",
    "In this embedding completion example, we use a simple curl call for illustration. There are three major components:\n",
    "\n",
    "* The host-url is your endpoint url with embed completion schema /v1/rerank.\n",
    "* The headers defines the content type as well as your api key.\n",
    "* The payload or data, which is your prompt detail and model hyper parameters."
   ]
  },
  {
   "source": [
    "!curl --request POST \\\n",
    "  --url https://your-endpoint.inference.ai/azure/com/v1/rerank \\\n",
    "  --header 'Authorization: Bearer your-auth-key' \\\n",
    "  --header 'Cohere-Version: 2022-12-06' \\\n",
    "  --header 'Content-Type: application/json' \\\n",
    "  --data '{\"query\": \"What is the capital of the United States?\", \"model\":\"rerank-english-v3.0\",\"return_documents\": true, \"documents\" : [\"Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.\",\"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.\",\"Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.\",\"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.\",\"Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.\"],\"top_n\": 3}'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HTTP Requests API Usage in Python\n",
    "Besides calling the API directly from command line tools. You can also programatically call them in Python. Here there is an embed example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "b'{\"id\":\"3750ff1f-a1d8-4824-89e4-3cd7b1eb6447\",\"results\":[{\"document\":{\"text\":\"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.\"},\"index\":3,\"relevance_score\":0.9990564},{\"document\":{\"text\":\"Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.\"},\"index\":4,\"relevance_score\":0.7516481},{\"document\":{\"text\":\"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.\"},\"index\":1,\"relevance_score\":0.08882029}],\"meta\":{\"api_version\":{\"version\":\"unspecified\",\"is_deprecated\":true},\"warnings\":[\"Please set an API version, for more information please refer to https://docs.cohere.com/versioning-reference\",\"Version is deprecated, for more information please refer to https://docs.cohere.com/versioning-reference\"],\"billed_units\":{\"search_units\":1}}}'\n"
     ]
    }
   ],
   "source": [
    "import urllib.request\n",
    "import json\n",
    "\n",
    "# Configure payload data sending to API endpoint\n",
    "data = {\n",
    "    \"query\": \"What is the capital of the United States?\",\n",
    "    \"model\": \"rerank-english-v3.0\",\n",
    "    \"return_documents\": True,\n",
    "    \"documents\": [\n",
    "        \"Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.\",\n",
    "        \"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.\",\n",
    "        \"Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.\",\n",
    "        \"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.\",\n",
    "        \"Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.\",\n",
    "    ],\n",
    "    \"top_n\": 3,\n",
    "}\n",
    "\n",
    "body = str.encode(json.dumps(data))\n",
    "\n",
    "# Replace the url with your API endpoint\n",
    "url = \"https://your-endpoint.inference.ai/azure/com/v1/rerank\"\n",
    "\n",
    "# Replace this with the key for the endpoint\n",
    "api_key = \"bearer <your-api-key>\"\n",
    "if not api_key:\n",
    "    raise Exception(\"API Key is missing\")\n",
    "\n",
    "headers = {\"Content-Type\": \"application/json\", \"Authorization\": (api_key)}\n",
    "\n",
    "req = urllib.request.Request(url, body, headers)\n",
    "\n",
    "try:\n",
    "    response = urllib.request.urlopen(req)\n",
    "    result = response.read()\n",
    "    print(result)\n",
    "except urllib.error.HTTPError as error:\n",
    "    print(\"The request failed with status code: \" + str(error.code))\n",
    "    # Print the headers - they include the requert ID and the timestamp, which are useful for debugging the failure\n",
    "    print(error.info())\n",
    "    print(error.read().decode(\"utf8\", \"ignore\"))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}