{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3inuQHTI-G-P"
      },
      "source": [
        "![JohnSnowLabs](https://nlp.johnsnowlabs.com/assets/images/logo.png)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0Cd4gz6vxHiQ"
      },
      "source": [
        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/JohnSnowLabs/spark-nlp-workshop/blob/master/legal-nlp/12.Coreference_Resolution.ipynb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "collapsed": false,
        "id": "gk3kZHmNj51v"
      },
      "source": [
        "#🎬 Installation"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "_914itZsj51v",
        "pycharm": {
          "is_executing": true
        }
      },
      "outputs": [],
      "source": [
        "! pip install -q johnsnowlabs"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "YPsbAnNoPt0Z"
      },
      "source": [
        "##🔗 Automatic Installation\n",
        "Using my.johnsnowlabs.com SSO"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "fY0lcShkj51w",
        "pycharm": {
          "is_executing": true
        }
      },
      "outputs": [],
      "source": [
        "from johnsnowlabs import nlp, legal\n",
        "\n",
        "# nlp.install(force_browser=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "hsJvn_WWM2GL"
      },
      "source": [
        "##🔗 Manual downloading\n",
        "If you are not registered in my.johnsnowlabs.com, you received a license via e-email or you are using Safari, you may need to do a manual update of the license.\n",
        "\n",
        "- Go to my.johnsnowlabs.com\n",
        "- Download your license\n",
        "- Upload it using the following command"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "i57QV3-_P2sQ"
      },
      "outputs": [],
      "source": [
        "from google.colab import files\n",
        "print('Please Upload your John Snow Labs License using the button below')\n",
        "license_keys = files.upload()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "xGgNdFzZP_hQ"
      },
      "source": [
        "- Install it"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "OfmmPqknP4rR"
      },
      "outputs": [],
      "source": [
        "nlp.install()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "DCl5ErZkNNLk"
      },
      "source": [
        "#📌 Starting"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "wRXTnNl3j51w"
      },
      "outputs": [],
      "source": [
        "spark = nlp.start()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9PSPOffJm5T8"
      },
      "source": [
        "#🔎 Legal Correference resolution"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "flBIgvG5LJHe"
      },
      "source": [
        "![image.png](data:image/png;base64,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)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6Q_ivA7kpPB8"
      },
      "source": [
        "📜Correference Resolution is the the task of finding all expressions that refer to the same entity in a text.\n",
        "\n",
        "This is very important in both Legal and Financial texts, where the name of the company is mentioned at the beginning of the document, but later on aliases of the company are used, intead of the official name.\n",
        "\n",
        "Let's take a look at some examples and how to solve them using Correference Resolution."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1jD5r4LupoJC"
      },
      "source": [
        "📜`'Armstrong Hardwood Flooring Company is a Tennessee corporation (known also as \"Company\"). The Company own certain Copyrights and Know-How which may be used in the Arizona Field, and in connection with the transactions contemplated by the Stock Purchase Agreement, Arizona desires to obtain a license from the Company Entities to use such Intellectual Property on the terms and subject to the conditions set forth herein.'`\n",
        "\n",
        "In the previous text, in the second sentence, `Company` refers to `Armstrong Hardwood Floowing Company`.\n",
        "\n",
        "📌There are two ways we can accomplish correference resolution:\n",
        "1. With a specific `SpanBertCorefModel` annotator;\n",
        "2. With NER and Relation Extraction;"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "P8xiIA53qAzd"
      },
      "source": [
        "#🔎 1. SpanBertCoref"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "avpl6hNXqe3i"
      },
      "source": [
        "SpanBertCorefModel annotator for Coreference Resolution on BERT and SpanBERT models based on [BERT for Coreference Resolution: Baselines and Analysis](https://arxiv.org/abs/1908.09091) paper. \n",
        "\n",
        "In Spark NLP, we include `SpanBertCorefModel` annotator as an implementation of this  SpanBert-based coreference resolution model."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "qdzTlziOjsL7",
        "outputId": "be42faab-10f8-4b75-bfbd-7c8cf6d6cf7d"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "spanbert_base_coref download started this may take some time.\n",
            "Approximate size to download 540.1 MB\n",
            "[OK!]\n"
          ]
        }
      ],
      "source": [
        "document_assembler = nlp.DocumentAssembler()\\\n",
        "    .setInputCol(\"text\")\\\n",
        "    .setOutputCol(\"document\")\n",
        "\n",
        "text_splitter = legal.TextSplitter()\\\n",
        "    .setInputCols([\"document\"])\\\n",
        "    .setOutputCol(\"sentences\")\n",
        "\n",
        "tokenizer = nlp.Tokenizer()\\\n",
        "    .setInputCols([\"sentences\"])\\\n",
        "    .setOutputCol(\"tokens\")\n",
        "\n",
        "corefResolution = nlp.SpanBertCorefModel()\\\n",
        "    .pretrained(\"spanbert_base_coref\")\\\n",
        "    .setInputCols([\"sentences\", \"tokens\"])\\\n",
        "    .setOutputCol(\"corefs\")\n",
        "\n",
        "pipeline = nlp.Pipeline(stages=[document_assembler, text_splitter, tokenizer, corefResolution])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "_HIbSJbgt3KY"
      },
      "source": [
        "###✔️ Who is \"the Company\" in this example❓"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "zl_-oEogthky",
        "outputId": "35a0d2ef-9260-461f-e4d5-02b2435441f0"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "+-----------------------------------+-----------------------------------------------------------------------------------------------------------------+\n",
            "|token                              |metadata                                                                                                         |\n",
            "+-----------------------------------+-----------------------------------------------------------------------------------------------------------------+\n",
            "|Armstrong Hardwood Flooring Company|{head.sentence -> -1, head -> ROOT, head.begin -> -1, head.end -> -1, sentence -> 0}                             |\n",
            "|The Company                        |{head.sentence -> 0, head -> Armstrong Hardwood Flooring Company, head.begin -> 0, head.end -> 34, sentence -> 1}|\n",
            "+-----------------------------------+-----------------------------------------------------------------------------------------------------------------+\n",
            "\n"
          ]
        }
      ],
      "source": [
        "example1 = 'Armstrong Hardwood Flooring Company is a Tennessee corporation (known also as \"Company\"). The Company own certain Copyrights and Know-How which may be used to the conditions set forth herein.'\n",
        "\n",
        "data = spark.createDataFrame([[example1]]).toDF(\"text\")\n",
        "\n",
        "model = pipeline.fit(data)\n",
        "\n",
        "model.transform(data).selectExpr(\"explode(corefs) AS coref\").selectExpr(\"coref.result as token\", \"coref.metadata\").show(truncate=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "xk69tCV3t5_x"
      },
      "source": [
        "###✔️ What is \"this Agreement\" in the example? And \"it\"❓"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "6_H1-luHox_t",
        "outputId": "789c4f31-d921-4076-b654-71717c6afc68"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "|token             |metadata                                                                                         |\n",
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "|this \" Agreement \"|{head.sentence -> -1, head -> ROOT, head.begin -> -1, head.end -> -1, sentence -> 0}             |\n",
            "|It                |{head.sentence -> 0, head -> this \" Agreement \", head.begin -> 38, head.end -> 53, sentence -> 1}|\n",
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "\n"
          ]
        }
      ],
      "source": [
        "example2 = 'This INTELLECTUAL PROPERTY AGREEMENT (this \"Agreement\") is dated as of December 31, 2018 (the \"Effective Date\").It was entered into by and between Armstrong Flooring (the \"Seller\") and AHF Holding (the \"Buyer\"). Seller and Buyer have entered into that certain Stock Purchase Agreement, dated November 14, 2018 (the \"Stock Purchase Agreement\")'\n",
        "\n",
        "data = spark.createDataFrame([[example2]]).toDF(\"text\")\n",
        "\n",
        "model = pipeline.fit(data)\n",
        "\n",
        "model.transform(data).selectExpr(\"explode(corefs) AS coref\").selectExpr(\"coref.result as token\", \"coref.metadata\").show(truncate=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "o_t1PbJKuETe"
      },
      "source": [
        "###✔️ Which date are we talking about❓"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Hf4H4Cxks32y",
        "outputId": "ff49aeef-5269-4b09-b313-0e8bb11f72de"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "|token             |metadata                                                                                         |\n",
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "|This Agreement    |{head.sentence -> -1, head -> ROOT, head.begin -> -1, head.end -> -1, sentence -> 0}             |\n",
            "|it                |{head.sentence -> 0, head -> This Agreement, head.begin -> 0, head.end -> 13, sentence -> 1}     |\n",
            "|December 31 , 2018|{head.sentence -> -1, head -> ROOT, head.begin -> -1, head.end -> -1, sentence -> 0}             |\n",
            "|that date         |{head.sentence -> 0, head -> December 31 , 2018, head.begin -> 30, head.end -> 46, sentence -> 1}|\n",
            "+------------------+-------------------------------------------------------------------------------------------------+\n",
            "\n"
          ]
        }
      ],
      "source": [
        "example3 = 'This Agreement is dated as of December 31, 2018 (the \"Effective Date\"). Seller and Buyer should sign it before the ending of that date.'\n",
        "\n",
        "data = spark.createDataFrame([[example3]]).toDF(\"text\")\n",
        "\n",
        "model = pipeline.fit(data)\n",
        "\n",
        "model.transform(data).selectExpr(\"explode(corefs) AS coref\").selectExpr(\"coref.result as token\", \"coref.metadata\").show(truncate=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3CHlz5rkuL_2"
      },
      "source": [
        "However, reality is that legal texts are often times, much longer and complex than those ones.\n",
        "\n",
        "Let's take a look at the following example:"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a0L2ECGSu0O1"
      },
      "source": [
        "###✔️ Who is Seller? Who is Buyer❓"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "mCcCI8XxvNn1"
      },
      "source": [
        "FAIL: We are unable to retrieve that information using SpanBertCoref."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "iGj2-FdlrpgD",
        "outputId": "8df9a0b9-2d67-47c5-d008-1ee5625eda6a"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "\u001b[31m\n",
            "+--------+----------------------------------------------------------------------------------------+\n",
            "|token   |metadata                                                                                |\n",
            "+--------+----------------------------------------------------------------------------------------+\n",
            "|Seller \"|{head.sentence -> -1, head -> ROOT, head.begin -> -1, head.end -> -1, sentence -> 1}    |\n",
            "|Seller \"|{head.sentence -> 1, head -> Seller \", head.begin -> 95, head.end -> 101, sentence -> 3}|\n",
            "+--------+----------------------------------------------------------------------------------------+\n",
            "\n",
            "\u001b[0m\n"
          ]
        }
      ],
      "source": [
        "example4 = 'This INTELLECTUAL PROPERTY AGREEMENT is entered into by and between Armstrong Flooring, Inc. (\"Seller\") and AHF Holding, Inc. (\"Buyer\"). \"Seller\" and \"Buyer\" have entered into that certain Stock Purchase Agreement, dated November 14, 2018 (the \"Stock Purchase Agreement\")'\n",
        "\n",
        "data = spark.createDataFrame([[example4]]).toDF(\"text\")\n",
        "\n",
        "model = pipeline.fit(data)\n",
        "\n",
        "print(\"\\x1b[31m\")\n",
        "model.transform(data).selectExpr(\"explode(corefs) AS coref\").selectExpr(\"coref.result as token\", \"coref.metadata\").show(truncate=False)\n",
        "print(\"\\x1b[0m\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "RNfgDSYgvYXI"
      },
      "source": [
        "Another disadvantage of this method is that you need to send all the text at once to resolve the correferences. If you miss the original lines where the concepts are defined, you will lose the reference.\n",
        "\n",
        "As an alternative, we can use NER and Relation Extraction, as shown in the next section.\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "99hvTbVtvc7d"
      },
      "source": [
        "#🔎 2. NER and Relation Extraction"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "VGBOmAeizY8u"
      },
      "source": [
        "We have several models trained in Models Hub (Spark NLP for Legal), which are able to detect aliases or secondary names in financial and legal documents.\n",
        "\n",
        "We are going to use this NER one:\n",
        "`https://nlp.johnsnowlabs.com/2022/08/12/legre_contract_doc_parties_en_3_2.html`\n",
        "\n",
        "After extracting the aliases, we will check which names they are referring to. To do this, we will use Relation Extraction. For this example, we will use this model:\n",
        "\n",
        "`https://nlp.johnsnowlabs.com/2022/08/17/legre_org_prod_alias_en_3_2.html`\n",
        "\n",
        "Let's see them in action."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "bPATySlKvgDh",
        "outputId": "df5df8a1-7146-4462-ce10-25d9ba606a9f"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "bert_embeddings_sec_bert_base download started this may take some time.\n",
            "Approximate size to download 390.4 MB\n",
            "[OK!]\n",
            "legner_orgs_prods_alias download started this may take some time.\n",
            "[OK!]\n",
            "legre_org_prod_alias download started this may take some time.\n",
            "[OK!]\n"
          ]
        }
      ],
      "source": [
        "documentAssembler = nlp.DocumentAssembler()\\\n",
        "        .setInputCol(\"text\")\\\n",
        "        .setOutputCol(\"document\")\n",
        "\n",
        "tokenizer = nlp.Tokenizer()\\\n",
        "        .setInputCols([\"document\"])\\\n",
        "        .setOutputCol(\"token\")\n",
        "\n",
        "embeddings = nlp.BertEmbeddings.pretrained(\"bert_embeddings_sec_bert_base\",\"en\") \\\n",
        "        .setInputCols([\"document\", \"token\"]) \\\n",
        "        .setOutputCol(\"embeddings\")\n",
        "\n",
        "ner_model = legal.NerModel.pretrained(\"legner_orgs_prods_alias\", \"en\", \"legal/models\")\\\n",
        "        .setInputCols([\"document\", \"token\", \"embeddings\"])\\\n",
        "        .setOutputCol(\"ner\")\n",
        "\n",
        "ner_converter = nlp.NerConverter()\\\n",
        "        .setInputCols([\"document\",\"token\",\"ner\"])\\\n",
        "        .setOutputCol(\"ner_chunk\")\n",
        "\n",
        "reDL = legal.RelationExtractionDLModel()\\\n",
        "    .pretrained(\"legre_org_prod_alias\", \"en\", \"legal/models\")\\\n",
        "    .setPredictionThreshold(0.99)\\\n",
        "    .setInputCols([\"ner_chunk\", \"document\"])\\\n",
        "    .setOutputCol(\"relations\")\n",
        "\n",
        "nlpPipeline = nlp.Pipeline(stages=[\n",
        "        documentAssembler,\n",
        "        tokenizer,\n",
        "        embeddings,\n",
        "        ner_model,\n",
        "        ner_converter,\n",
        "        reDL])"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "YJo1E2lX05Kh"
      },
      "outputs": [],
      "source": [
        "example4 = 'This INTELLECTUAL PROPERTY AGREEMENT is entered into by and between Armstrong Flooring, Inc. (the \"Seller\") and AHF Holding, Inc., a Delaware Corporation (the \"Buyer\").'\n",
        "\n",
        "data = spark.createDataFrame([[\"\"]]).toDF(\"text\")\n",
        "\n",
        "model = nlpPipeline.fit(data)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "c-HnYlJ60-qk"
      },
      "outputs": [],
      "source": [
        "lmodel = nlp.LightPipeline(model)\n",
        "res = lmodel.fullAnnotate(example4)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "r4XJXvPP3rC5",
        "outputId": "10dfd877-1ca5-41dc-f2d2-bb5071037d7b"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Armstrong Flooring, Inc. - has_alias - Seller (confidence: 0.9938087)\n",
            "AHF Holding, Inc., a Delaware Corporation - has_alias - Buyer (confidence: 0.9923051)\n"
          ]
        }
      ],
      "source": [
        "aliases = dict()\n",
        "for r in res:\n",
        "  for rel in r['relations']:\n",
        "    if rel.result != 'no_rel':\n",
        "      aliases.setdefault(rel.metadata['chunk2'], []).append(rel.metadata['chunk1'])\n",
        "      print(f\"{rel.metadata['chunk1']} - {rel.result} - {rel.metadata['chunk2']} (confidence: {rel.metadata['confidence']})\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "QugS7tnp8hs8",
        "outputId": "b831b085-0f84-478c-9f98-a189059d1be5"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "{'Seller': ['Armstrong Flooring, Inc.'],\n",
              " 'Buyer': ['AHF Holding, Inc., a Delaware Corporation']}"
            ]
          },
          "execution_count": 15,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "aliases"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ukN_yz6r5naW"
      },
      "source": [
        "Being that done, you can process the rest of the document, detecting entities as Seller, Buyer, etc with either NER or ContextualParsers, and be ablet o disambiguate it using the results of the previous model"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "Kmd0yjEF51Up"
      },
      "outputs": [],
      "source": [
        "example5 = '\"Seller\" and \"Buyer\" have entered into that certain Stock Purchase Agreement, dated November 14, 2018 (the \"Stock Purchase Agreement\")'\n",
        "\n",
        "nlpPipeline = nlp.Pipeline(stages=[\n",
        "        documentAssembler,\n",
        "        tokenizer,\n",
        "        embeddings,\n",
        "        ner_model,\n",
        "        ner_converter])\n",
        "\n",
        "data = spark.createDataFrame([[\"\"]]).toDF(\"text\")\n",
        "\n",
        "model = nlpPipeline.fit(data)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "6hFXNZU659Zh"
      },
      "outputs": [],
      "source": [
        "lmodel = nlp.LightPipeline(model)\n",
        "res = lmodel.fullAnnotate(example5)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "MFUb4Xk-71yy",
        "outputId": "78942ecc-3760-434e-86f9-ab300cdc243f"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Seller is Armstrong Flooring, Inc.\n",
            "Buyer is AHF Holding, Inc., a Delaware Corporation\n"
          ]
        }
      ],
      "source": [
        "for r in res:\n",
        "  for ner_chunk in r['ner_chunk']:\n",
        "    print(f\"{ner_chunk.result} is {aliases[ner_chunk.result][0]}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Zcvmnmzx89i9"
      },
      "source": [
        "The big advantage of using this method is that you don't need to process the whole text to know the correferences. You can detect first the aliases, store them and then resolve the correferences with NER and RE."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bi-OzrHX82JJ"
      },
      "source": [
        "#🔎 3. Question Answering"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "eY40Q_sm9hcm"
      },
      "source": [
        "This is the third option from retrieving correferences. You can detect the alias and ask questions on the fly about what they refer to.\n",
        "\n",
        "Let's see an example."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "3WDfLkYm-fQJ"
      },
      "outputs": [],
      "source": [
        "context = 'This INTELLECTUAL PROPERTY AGREEMENT is entered into by and between Armstrong Flooring, Inc. (\"Seller\") and AHF Holding, Inc. (\"Buyer\").'.lower()\n",
        "question1 = 'Which company is the Buyer'.lower()\n",
        "question2 = 'Which company is the Seller'.lower()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "zNBbwlke84fD",
        "outputId": "0deed14c-cb51-4b54-9415-16d84d860be3"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "legqa_bert_large download started this may take some time.\n",
            "Approximate size to download 1.2 GB\n",
            "[OK!]\n"
          ]
        }
      ],
      "source": [
        "document_assembler = nlp.MultiDocumentAssembler()\\\n",
        "    .setInputCols([\"question\", \"context\"]) \\\n",
        "    .setOutputCols([\"document_question\", \"document_context\"])\n",
        "\n",
        "spanClassifier = nlp.BertForQuestionAnswering.pretrained(\"legqa_bert_large\",\"en\", \"legal/models\")\\\n",
        "    .setInputCols([\"document_question\", \"document_context\"]) \\\n",
        "    .setOutputCol(\"answer\") \\\n",
        "    .setCaseSensitive(False)\n",
        "\n",
        "pipeline = nlp.Pipeline().setStages([\n",
        "    document_assembler,\n",
        "    spanClassifier\n",
        "])"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "bJdS9HFR-r6T"
      },
      "outputs": [],
      "source": [
        "qa = [[question1, context], [question2, context]]"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Xc7_sF3l_3nJ",
        "outputId": "66f14d3e-e1e8-49e7-c2a6-b21abdead3d6"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "+----------------------------+\n",
            "|result                      |\n",
            "+----------------------------+\n",
            "|[ahf holding , inc .]       |\n",
            "|[armstrong flooring , inc .]|\n",
            "+----------------------------+\n",
            "\n"
          ]
        }
      ],
      "source": [
        "example = spark.createDataFrame(qa).toDF(\"question\", \"context\")\n",
        "\n",
        "result = pipeline.fit(example).transform(example)\n",
        "\n",
        "result.select('answer.result').show(truncate=False)"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "machine_shape": "hm",
      "provenance": []
    },
    "gpuClass": "standard",
    "kernelspec": {
      "display_name": "tf-gpu",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.9.7 (default, Sep 16 2021, 16:59:28) [MSC v.1916 64 bit (AMD64)]"
    },
    "vscode": {
      "interpreter": {
        "hash": "3f47d918ae832c68584484921185f5c85a1760864bf927a683dc6fb56366cc77"
      }
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}