{
  "cells": [
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Managing Schemas"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The Bailo python client enables intuitive interaction with the Bailo service, from within a python environment. This example notebook will run through the following concepts:\n",
        "\n",
        "* Creating a new schema on Bailo.\n",
        "* Retrieving schemas from the service.\n",
        "\n",
        "Prerequisites:\n",
        "\n",
        "* Python 3.9 or higher (including a notebook environment for this demo).\n",
        "* A local or remote Bailo service (see https://github.com/gchq/Bailo)."
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Introduction"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The Bailo python client is split into two sub-packages: **core** and **helper**.\n",
        "\n",
        "* **Core:** For direct interactions with the service endpoints.\n",
        "* **Helper:** For more intuitive interactions with the service, using classes (e.g. Model) to handle operations.\n",
        "\n",
        "In order to create helper classes, you will first need to instantiate a `Client()` object from the core. By default, this object will not support any authentication. However, Bailo also supports PKI authentication, which you can use from Python by passing a `PkiAgent()` object into the `Client()` object when you instantiate it."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Necessary import statements\n",
        "\n",
        "from bailo import Client, Schema, SchemaKind\n",
        "import random\n",
        "import string\n",
        "\n",
        "# Instantiating the PkiAgent(), if using.\n",
        "# agent = PkiAgent(cert='', key='', auth='')\n",
        "\n",
        "# Instantiating the Bailo client\n",
        "\n",
        "client = Client(\"http://127.0.0.1:8080\") # <- INSERT BAILO URL (if not hosting locally)"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Creating a new schema"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In this section, we will create a new schema using the `Schema.create()` classmethod. On the Bailo service, a schema must consist of 5 parameters upon creation. These are **schema_id**, **name**, **description**, **kind** and **json_schema**. Below, we use the `Client()` object created before when instantiating the new `Schema()` object. In this instance, **schema_id** is generated using a random generator function, however any unique identifier would suffice.\n",
        "\n",
        "NOTE: This creates the schema on your Bailo service too! This operation is typically reserved for administrators."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "def random_generator(N=10):\n",
        "    return \"\".join(random.choices(string.ascii_uppercase + string.digits, k=N))\n",
        "\n",
        "json_schema = {\n",
        "    \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n",
        "    \"type\": \"object\",\n",
        "    \"properties\": {\n",
        "        \"overview\": {\n",
        "            \"title\": \"Overview\",\n",
        "            \"description\": \"Summary of the model functionality.\",\n",
        "            \"type\": \"object\",\n",
        "            \"properties\": {\n",
        "                \"modelOverview\": {\n",
        "                    \"title\": \"What does the model do?\",\n",
        "                    \"description\": \"A description of what the model does.\",\n",
        "                    \"type\": \"string\",\n",
        "                    \"minLength\": 1,\n",
        "                    \"maxLength\": 5000,\n",
        "                },\n",
        "                \"tags\": {\n",
        "                    \"title\": \"Descriptive tags for the model.\",\n",
        "                    \"description\": \"These tags will be searchable and will help others find this model.\",\n",
        "                    \"type\": \"array\",\n",
        "                    \"widget\": \"tagSelectorBeta\",\n",
        "                    \"items\": {\"type\": \"string\"},\n",
        "                    \"uniqueItems\": True,\n",
        "                },\n",
        "            },\n",
        "            \"required\": [],\n",
        "            \"additionalProperties\": False,\n",
        "        },\n",
        "    },\n",
        "    \"required\": [],\n",
        "    \"additionalProperties\": False,\n",
        "}\n",
        "\n",
        "schema = Schema.create(\n",
        "    client=client,\n",
        "    schema_id=random_generator(),\n",
        "    name=\"Test\",\n",
        "    description=\"Example Description\",\n",
        "    kind=SchemaKind.MODEL,\n",
        "    json_schema=json_schema\n",
        ")\n",
        "\n",
        "schema_id = schema.schema_id"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Retrieving an existing schema"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Using the .from_id() method"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In this section, we will retrieve our previous schema using the `Schema.from_id()` classmethod. This will create your `Schema()` object as before, but using existing information retrieved from the service."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "schema = Schema.from_id(client=client, schema_id=schema_id)\n",
        "\n",
        "schema.description"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python"
    },
    "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.12"
    },
    "orig_nbformat": 4
  },
  "nbformat": 4,
  "nbformat_minor": 2
}