spark-nlp 4.2.6__py2.py3-none-any.whl → 6.2.1__py2.py3-none-any.whl

sparknlp/annotator/ner/ner_dl_graph_checker.py

@@ -0,0 +1,293 @@
+#  Copyright 2017-2025 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""Contains classes for NerDL."""
+
+from pyspark.ml.util import JavaMLReadable
+
+import sparknlp.internal as _internal
+from sparknlp.common import *
+
+
+class NerDLGraphChecker(
+    JavaEstimator,
+    JavaMLWritable,
+    _internal.ParamsGettersSetters,
+):
+    """Checks whether a suitable NerDL graph is available for the given training dataset, before any
+    computations/training is done. This annotator is useful for custom training cases, where
+    specialized graphs are needed.
+
+    This annotator will fill graph hyperparameters as metadata in the label column, which will be
+    available for NerDLApproach, saving computations.
+
+    Important: This annotator should be used or positioned before any embedding or NerDLApproach
+    annotators in the pipeline and will process the whole dataset to extract the required graph parameters.
+
+    This annotator requires a dataset with at least two columns: one with tokens and one with the
+    labels. In addition, it requires the used embedding annotator in the pipeline to extract the
+    suitable embedding dimension.
+
+    For extended examples of usage, see the`Examples 
+    <https://github.com/JohnSnowLabs/spark-nlp/blob/master//home/ducha/Workspace/scala/spark-nlp-feature/examples/python/training/english/dl-ner/ner_dl_graph_checker.ipynb>`__ 
+    and the `NerDLGraphCheckerTestSpec 
+    <https://github.com/JohnSnowLabs/spark-nlp/blob/master/src/test/scala/com/johnsnowlabs/nlp/annotators/ner/dl/NerDLGraphCheckerTestSpec.scala>`__.
+
+    ==================================== ======================
+    Input Annotation types               Output Annotation type
+    ==================================== ======================
+    ``DOCUMENT, TOKEN``                  `NONE`
+    ==================================== ======================
+
+    Parameters
+    ----------
+    inputCols
+        Column names of input annotations
+    labelColumn
+        Column name for data labels
+    embeddingsDim
+        Dimensionality of embeddings
+
+    Examples
+    --------
+    >>> import sparknlp
+    >>> from sparknlp.base import *
+    >>> from sparknlp.annotator import *
+    >>> from pyspark.ml import Pipeline
+
+    This CoNLL dataset already includes a sentence, token and label
+    column with their respective annotator types. If a custom dataset is used,
+    these need to be defined with for example:
+
+    >>> conll = CoNLL()
+    >>> trainingData = conll.readDataset(spark, "src/test/resources/conll2003/eng.train")
+    >>> embeddings = BertEmbeddings \\
+    ...     .pretrained() \\
+    ...     .setInputCols(["sentence", "token"]) \\
+    ...     .setOutputCol("embeddings")
+    
+    This annotatorr requires the data for NerDLApproach graphs: text, tokens, labels and the embedding model
+
+    >>> nerDLGraphChecker = NerDLGraphChecker() \\
+    ...     .setInputCols(["sentence", "token"]) \\
+    ...     .setLabelColumn("label") \\
+    ...     .setEmbeddingsModel(embeddings)
+    >>> nerTagger = NerDLApproach() \\
+    ...     .setInputCols(["sentence", "token", "embeddings"]) \\
+    ...     .setLabelColumn("label") \\
+    ...     .setOutputCol("ner") \\
+    ...     .setMaxEpochs(1) \\
+    ...     .setRandomSeed(0) \\
+    ...     .setVerbose(0)
+    >>> pipeline = Pipeline().setStages([nerDLGraphChecker, embeddings, nerTagger])
+    
+    If we now fit the model with a graph missing, then an exception is raised.
+
+    >>> pipelineModel = pipeline.fit(trainingData)
+    """
+
+    inputCols = Param(
+        Params._dummy(),
+        "inputCols",
+        "Input columns",
+        typeConverter=TypeConverters.toListString,
+    )
+
+    def setInputCols(self, *value):
+        """Sets column names of input annotations.
+
+        Parameters
+        ----------
+        *value : List[str]
+            Input columns for the annotator
+        """
+        if type(value[0]) == str or type(value[0]) == list:
+            # self.inputColsValidation(value)
+            if len(value) == 1 and type(value[0]) == list:
+                return self._set(inputCols=value[0])
+            else:
+                return self._set(inputCols=list(value))
+        else:
+            raise TypeError(
+                "InputCols datatype not supported. It must be either str or list"
+            )
+
+    labelColumn = Param(
+        Params._dummy(),
+        "labelColumn",
+        "Column with label per each token",
+        typeConverter=TypeConverters.toString,
+    )
+
+    def setLabelColumn(self, value):
+        """Sets name of column for data labels.
+
+        Parameters
+        ----------
+        value : str
+            Column for data labels
+        """
+        return self._set(labelColumn=value)
+
+    embeddingsDim = Param(
+        Params._dummy(),
+        "embeddingsDim",
+        "Dimensionality of embeddings",
+        typeConverter=TypeConverters.toInt,
+    )
+
+    def setEmbeddingsDim(self, value: int):
+        """Sets Dimensionality of embeddings
+
+        Parameters
+        ----------
+        value : int
+            Dimensionality of embeddings
+        """
+        return self._set(embeddingsDim=value)
+
+    def setEmbeddingsModel(self, model: HasEmbeddingsProperties):
+        """
+        Get embeddingsDim from a given embeddings model, if possible.
+        Falls back to setEmbeddingsDim if dimension cannot be obtained automatically.
+        """
+        # Try Python API first
+        if hasattr(model, "getDimension"):
+            dim = model.getDimension()
+            return self.setEmbeddingsDim(int(dim))
+        # Try JVM side if available
+        if hasattr(model, "_java_obj") and hasattr(model._java_obj, "getDimension"):
+            dim = int(model._java_obj.getDimension())
+            return self.setEmbeddingsDim(dim)
+        raise ValueError(
+            "Could not infer embeddings dimension from provided model. "
+            "Use setEmbeddingsDim(dim) explicitly."
+        )
+
+    inputAnnotatorTypes = [
+        AnnotatorType.DOCUMENT,
+        AnnotatorType.TOKEN,
+    ]
+
+    graphFolder = Param(
+        Params._dummy(),
+        "graphFolder",
+        "Folder path that contain external graph files",
+        TypeConverters.toString,
+    )
+
+    def setGraphFolder(self, p):
+        """Sets folder path that contain external graph files.
+
+        Parameters
+        ----------
+        p : str
+            Folder path that contain external graph files
+        """
+        return self._set(graphFolder=p)
+
+    @keyword_only
+    def __init__(self):
+        _internal.ParamsGettersSetters.__init__(self)
+        classname = "com.johnsnowlabs.nlp.annotators.ner.dl.NerDLGraphChecker"
+        self.__class__._java_class_name = classname
+        self._java_obj = self._new_java_obj(classname, self.uid)
+        # self._setDefault()
+
+    def _create_model(self, java_model):
+        return NerDLGraphCheckerModel(java_model=java_model)
+
+
+class NerDLGraphCheckerModel(
+    JavaModel,
+    JavaMLWritable,
+    JavaMLReadable,
+    _internal.ParamsGettersSetters,
+):
+    """Resulting model from `NerDLGraphChecker`, that updates dataframe metadata (label column)
+    with NerDLGraph parameters. It does not perform any actual data transformations, as the
+    checks/computations are done during the `fit` phase.
+
+    This annotator should never be used directly.
+    """
+
+    inputAnnotatorTypes = [
+        AnnotatorType.DOCUMENT,
+        AnnotatorType.TOKEN,
+    ]
+
+    @keyword_only
+    def __init__(
+            self,
+            classname="com.johnsnowlabs.nlp.annotators.ner.dl.NerDLGraphCheckerModel",
+            java_model=None,
+    ):
+        # Custom init, different from AnnotatorModel
+        # We don't have a output annotation column, so we inherit directly from JavaModel
+        if java_model is not None:
+            super(NerDLGraphCheckerModel, self).__init__(java_model=java_model)
+            self._java_obj = java_model
+            self._transfer_params_from_java()
+        elif classname:
+            super(NerDLGraphCheckerModel, self).__init__()
+            self.__class__._java_class_name = classname
+            self._java_obj = self._new_java_obj(classname)
+
+    # Metadata keys for graph parameters
+    graphParamsMetadataKey = "NerDLGraphCheckerParams"
+    embeddingsDimKey = "embeddingsDim"
+    labelsKey = "labels"
+    charsKey = "chars"
+    dsLenKey = "dsLen"
+
+    labelColumn = Param(
+        Params._dummy(),
+        "labelColumn",
+        "Column with label per each token",
+        typeConverter=TypeConverters.toString,
+    )
+
+    embeddingsDim = Param(
+        Params._dummy(),
+        "embeddingsDim",
+        "Dimensionality of embeddings",
+        typeConverter=TypeConverters.toInt,
+    )
+
+    labels = Param(
+        Params._dummy(),
+        "labels",
+        "Labels in the dataset",
+        typeConverter=TypeConverters.toListString,
+    )
+
+    chars = Param(
+        Params._dummy(),
+        "chars",
+        "Set of characters in the dataset",
+        typeConverter=TypeConverters.toListString,
+    )
+
+    graphFolder = Param(
+        Params._dummy(),
+        "graphFolder",
+        "Folder path that contain external graph files",
+        typeConverter=TypeConverters.toString,
+    )
+
+    dsLen = Param(
+        Params._dummy(),
+        "dsLen",
+        "Length of the training dataset.",
+        typeConverter=TypeConverters.toInt,
+    )

sparknlp/annotator/ner/ner_overwriter.py

@@ -21,8 +21,8 @@ class NerOverwriter(AnnotatorModel):
 
     The input for this Annotator have to be entities that are already extracted,
     Annotator type ``NAMED_ENTITY``. The strings specified with
-    :meth:`.setStopWords` will have new entities assigned to, specified with
-    :meth:`.setNewResult`.
+    :meth:`.NerOverwriter.setStopWords` will have new entities assigned to, specified
+    with :meth:`.NerOverwriter.setNewResult`.
 
     ====================== ======================
     Input Annotation types Output Annotation type

sparknlp/annotator/ner/zero_shot_ner_model.py

@@ -0,0 +1,173 @@
+#  Copyright 2017-2023 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from sparknlp.common import *
+from sparknlp.annotator.classifier_dl import RoBertaForQuestionAnswering
+
+
+class ZeroShotNerModel(RoBertaForQuestionAnswering, HasEngine):
+    """ZeroShotNerModel implements zero shot named entity recognition by utilizing RoBERTa
+    transformer models fine tuned on a question answering task.
+
+    Its input is a list of document annotations and it automatically generates questions which are
+    used to recognize entities. The definitions of entities is given by a dictionary structures,
+    specifying a set of questions for each entity. The model is based on
+    RoBertaForQuestionAnswering.
+
+    For more extended examples see the
+    `Examples <https://github.com/JohnSnowLabs/spark-nlp/blob/master/examples/python/annotation/text/english/named-entity-recognition/ZeroShot_NER.ipynb>`__.
+
+    Pretrained models can be loaded with ``pretrained`` of the companion object:
+
+    .. code-block:: python
+
+       zeroShotNer = ZeroShotNerModel.pretrained() \\
+           .setInputCols(["document"]) \\
+           .setOutputCol("zer_shot_ner")
+
+    ====================== ======================
+    Input Annotation types Output Annotation type
+    ====================== ======================
+    ``DOCUMENT, TOKEN``    ``NAMED_ENTITY``
+    ====================== ======================
+
+    Parameters
+    ----------
+    entityDefinitions
+        A dictionary with definitions of named entities. The keys of dictionary are the entity labels and the
+        values are lists of questions. For example:
+              {
+                "CITY": ["Which city?", "Which town?"],
+                "NAME": ["What is her name?", "What is his name?"]}
+
+    predictionThreshold
+        Minimal confidence score to encode an entity (Default: 0.01f)
+    ignoreEntities
+        A list of entity labels which are discarded from the output.
+
+    References
+    ----------
+    `RoBERTa: A Robustly Optimized BERT Pretraining Approach <https://arxiv.org/abs/1907.11692>`__ : for details about the RoBERTa transformer
+    :class:`.RoBertaForQuestionAnswering` : for the SparkNLP implementation of RoBERTa question  answering
+
+    Examples
+    --------
+    >>> document_assembler = DocumentAssembler() \\
+    ...     .setInputCol("text") \\
+    ...     .setOutputCol("document")
+    >>> sentence_detector = SentenceDetector() \\
+    ...     .setInputCols(["document"]) \\
+    ...     .setOutputCol("sentence")
+    >>> tokenizer = Tokenizer() \\
+    ...     .setInputCols(["sentence"]) \\
+    ...     .setOutputCol("token")
+    >>> zero_shot_ner = ZeroShotNerModel() \\
+    ...     .pretrained() \\
+    ...     .setEntityDefinitions(
+    ...         {
+    ...             "NAME": ["What is his name?", "What is my name?", "What is her name?"],
+    ...             "CITY": ["Which city?", "Which is the city?"]
+    ...         }) \\
+    ...     .setInputCols(["sentence", "token"]) \\
+    ...     .setOutputCol("zero_shot_ner") \\
+    >>> data = spark.createDataFrame(
+    ...         [["My name is Clara, I live in New York and Hellen lives in Paris."]]
+    ...     ).toDF("text")
+    >>> Pipeline() \\
+    ...     .setStages([document_assembler, sentence_detector, tokenizer, zero_shot_ner]) \\
+    ...     .fit(data) \\
+    ...     .transform(data) \\
+    ...     .selectExpr("document", "explode(zero_shot_ner) AS entity") \\
+    ...     .select(
+    ...         "document.result",
+    ...         "entity.result",
+    ...         "entity.metadata.word",
+    ...         "entity.metadata.confidence",
+    ...         "entity.metadata.question") \\
+    ...     .show(truncate=False)
+    +-----------------------------------------------------------------+------+------+----------+------------------+
+    |result                                                           |result|word  |confidence|question          |
+    +-----------------------------------------------------------------+------+------+----------+------------------+
+    |[My name is Clara, I live in New York and Hellen lives in Paris.]|B-CITY|Paris |0.5328949 |Which is the city?|
+    |[My name is Clara, I live in New York and Hellen lives in Paris.]|B-NAME|Clara |0.9360068 |What is my name?  |
+    |[My name is Clara, I live in New York and Hellen lives in Paris.]|B-CITY|New   |0.83294415|Which city?       |
+    |[My name is Clara, I live in New York and Hellen lives in Paris.]|I-CITY|York  |0.83294415|Which city?       |
+    |[My name is Clara, I live in New York and Hellen lives in Paris.]|B-NAME|Hellen|0.45366877|What is her name? |
+    +-----------------------------------------------------------------+------+------+----------+------------------+
+    """
+    inputAnnotatorTypes = [AnnotatorType.DOCUMENT, AnnotatorType.TOKEN]
+    outputAnnotatorType = AnnotatorType.NAMED_ENTITY
+
+    name = "ZeroShotNerModel"
+
+    predictionThreshold = Param(Params._dummy(),
+                                "predictionThreshold",
+                                "Minimal confidence score to encode an entity (default is 0.1)",
+                                TypeConverters.toFloat)
+
+    ignoreEntities = Param(Params._dummy(),
+                           "ignoreEntities",
+                           "List of entities to ignore",
+                           TypeConverters.toListString)
+
+    def setPredictionThreshold(self, threshold):
+        """Sets the minimal confidence score to encode an entity
+
+        Parameters
+        ----------
+        threshold : float
+           minimal confidence score to encode an entity (default is 0.1)
+        """
+        return self._set(predictionThreshold=threshold)
+
+    def setEntityDefinitions(self, definitions):
+        """Set entity definitions
+
+        Parameters
+        ----------
+        definitions : dict[str, list[str]]
+
+        """
+        self._call_java("setEntityDefinitions", definitions)
+
+        return self
+
+    def getClasses(self):
+        """
+        Returns the list of entities which are recognized
+        """
+        return self._call_java("getEntities")
+
+    @keyword_only
+    def __init__(self, classname="com.johnsnowlabs.nlp.annotators.ner.dl.ZeroShotNerModel", java_model=None):
+        super(ZeroShotNerModel, self).__init__(
+            classname=classname,
+            java_model=java_model
+        )
+        self._setDefault(
+            predictionThreshold=0.01,
+            ignoreEntities=[]
+        )
+
+    @staticmethod
+    def pretrained(name="zero_shot_ner_roberta", lang="en", remote_loc=None):
+        from sparknlp.pretrained import ResourceDownloader
+        return ResourceDownloader.downloadModel(ZeroShotNerModel, name, lang, remote_loc,
+                                                j_dwn='PythonResourceDownloader')
+
+    @staticmethod
+    def load(path):
+        from sparknlp.internal import _RobertaQAToZeroShotNerLoader
+        jModel = _RobertaQAToZeroShotNerLoader(path)._java_obj
+        return ZeroShotNerModel(java_model=jModel)

sparknlp/annotator/normalizer.py

@@ -20,8 +20,8 @@ class Normalizer(AnnotatorApproach):
     all dirty characters from text following a regex pattern and transforms
     words based on a provided dictionary
 
-    For extended examples of usage, see the `Spark NLP Workshop
-    <https://github.com/JohnSnowLabs/spark-nlp-workshop/blob/master/tutorials/Certification_Trainings/Public/2.Text_Preprocessing_with_SparkNLP_Annotators_Transformers.ipynb>`__.
+    For extended examples of usage, see the `Examples
+    <https://github.com/JohnSnowLabs/spark-nlp/blob/master/examples/python/annotation/text/english/document-normalizer/document_normalizer_notebook.ipynb>`__.
 
     ====================== ======================
     Input Annotation types Output Annotation type

sparknlp/annotator/openai/__init__.py

@@ -0,0 +1,16 @@
+#  Copyright 2017-2023 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""Module of annotators for openai integration."""
+from sparknlp.annotator.openai.openai_completion import *
+from sparknlp.annotator.openai.openai_embeddings import *