examples/server_examples.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial for working with Altair AI Hub\n",
    "\n",
    "In order to use this notebook you need to have the [rapidminer](https://github.com/rapidminer/python-rapidminer) package installed in your current Python environment. For installation instructions, consult the [README](https://github.com/rapidminer/python-rapidminer).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Connect to Altair AI Hub\n",
    "\n",
    "In order to connect to Altair AI Hub, provide credentials to be able to connect to the server. The input required from the user:\n",
    " - authentication_server: the url of the Keycloak authentication server with the /auth postfix\n",
    " - offline_token: after logging to the AI hub instance, with the correct permissions you should be able to reach your {AI Hub url}/get-token page, where you can find the value of the offline token\n",
    " - client_secret: on the above page you should be able to see the client secret for this token-tool client\n",
    "If you want to fully automate the execution, you can provide both of these with additional parameters, besides other parameters as well. For more details, please consult the [documentation](https://github.com/rapidminer/python-rapidminer/blob/master/docs/api/Server.md)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import rapidminer\n",
    "\n",
    "connector = rapidminer.Server()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It will ask you about information and credentials to be able to authenticate. However, it is also possible to configure it by the following way: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import rapidminer\n",
    "connector = rapidminer.Server(\"https://myserver.mycompany.com:8080\", \n",
    "                              authentication_server=\"https:///myserver.mycompany.com:8081/auth\", \n",
    "                              offline_token=\"qwert12345\", client_secret=\"qwert12345\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Running an Altair AI process\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may want to run a process that resides in a versioned project. Note that inputs and outputs are not allowed, as the process can only directly read from the project and potentially write back using an automatic commit and push. To run the latest version of a process in a project, use the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "process = rapidminer.ProjectLocation(\"sample-dev\", \"processes/normalize_iris.rmp\")\n",
    "connector.run_process(path=process)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can add the `project` name and `path` to the process to the `run_process` method too. You can also define `macros` and the `queue`, like the following way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connector.run_process(project=\"sample-dev\", path=\"processes/normalize_iris.rmp\", queue=\"DEFAULT\", macros={\"sample_size\" : 100})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using Connections\n",
    "Connections defined in the AI Hub repository are available using the following function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connections = connector.get_connections(\"sample-dev\")\n",
    "connections"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Accessing the field values of these connections are possible through several ways, see examples below. Use these values to establish a connection to a database, cloud service, etc. using an appropriate Python package (e.g. _sqlalchemy_)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas\n",
    "from sqlalchemy import create_engine\n",
    "conn = connections[\"sample-postgres\"]\n",
    "postgres_str = (\"postgresql://{username}:{password}@{host}:{port}/{dbname}\"\n",
    "    .format(username=conn.user,\n",
    "        password=conn.password,\n",
    "        host=conn.values[\"host\"],\n",
    "        port=conn.values[\"port\"],\n",
    "        dbname=conn.values[\"database\"]\n",
    "    )\n",
    ")\n",
    "cnx = create_engine(postgres_str).raw_connection()\n",
    "pandas.read_sql_query(\"SELECT * FROM test_date_types_1\", con=cnx)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get projects\n",
    "\n",
    "You can also get the available projects in the Server the following way:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connector.get_projects()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It returns a Connections object listing connections from the AI Hub project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get queues\n",
    "\n",
    "You can also get the queues in a Server:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "connector.get_queues()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It returns a JSON array of objects representing each queue with its properties."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Web Api endpoints"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The WebApi class allows you to easily score a deployed service. You only need to provide the Altair AI Hub URL and the particular service endpoint to create a class instance. After that, you can use the predict method to do scoring and get the result in pandas DataFrame format, or in JSON format (depending on the value of return_json flag). For instructions on how to deploy Web Api endpoint on Altair AI Hub, please refer to its documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = [\n",
    "    {\n",
    "        \"a1\": 5.1,\n",
    "        \"a2\": 3.5,\n",
    "        \"a3\": 1.4,\n",
    "        \"a4\": 0.2\n",
    "    }\n",
    "]\n",
    "macros = {\n",
    "    'macro1': 1,\n",
    "    'macro2': 'value'\n",
    "}\n",
    "\n",
    "# Predicting on JSON expecting a DataFrame as a result\n",
    "wa = rapidminer.WebApi(\n",
    "    \"http://mycompany.com:8090\", \"score-sales/score1\")\n",
    "prediction = wa.predict(data, macros)\n",
    "\n",
    "# Predicting on pandas DataFrame expecting JSON as a result\n",
    "df = pandas.DataFrame(data)\n",
    "wa = rapidminer.WebApi(\n",
    "    \"http://mycompany.com:8090\", \"score-sales/score1\")\n",
    "prediction = wa.predict(df, macros, return_json=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where the Web Api endpoint is at `\"score-sales/score1\"` that can be applied to pandas DataFrame `data`, or list of JSON objects, with macros as parameters, and the resulting `prediction` is a pandas DataFrame as well (or JSON object). You can also define the Web Api group by defining the `web_api_group` parameter, by default it uses the `DEFAULT` one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be configured to use three different authentication methods: Basic, OAuth, Long Living token."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Basic Auth"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wa = rapidminer.WebApi(\"http://mycompany.com:8090\", \"score-sales/score1\",\n",
    "                       authentication='basic', username=\"my_user\", password=\"my_password\")\n",
    "prediction = wa.predict(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### OAuth using Keycloak and offline_token"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wa = rapidminer.WebApi(\"https://myserver.mycompany.com:8090\", \"score-sales/score1\",\n",
    "                        authentication='oauth', authentication_server=\"https:///myserver.mycompany.com:8090/auth\",\n",
    "                          offline_token=\"qwert12345\", client_secret=\"qwert12345\")\n",
    "prediction = wa.predict(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Long living token"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wa = rapidminer.WebApi(\"http//mycompany.com\", \"score-sales/score1\", \n",
    "                       authentication='apitoken', apitoken=\"my_token\")\n",
    "prediction = wa.predict(data)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.5 (conda)",
   "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.10.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}