elasticsearch-haystack 0.0.1__py3-none-any.whl

elasticsearch_haystack/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2023-present Silvano Cerza <silvanocerza@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+__version__ = "0.0.1"

elasticsearch_haystack/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2023-present Silvano Cerza <silvanocerza@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+from elasticsearch_haystack.document_store import ElasticsearchDocumentStore
+
+__all__ = ["ElasticsearchDocumentStore"]

elasticsearch_haystack/bm25_retriever.py

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2023-present Silvano Cerza <silvanocerza@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any, Dict, List, Optional
+
+from haystack.preview import component, default_from_dict, default_to_dict
+from haystack.preview.dataclasses import Document
+
+from elasticsearch_haystack.document_store import ElasticsearchDocumentStore
+
+
+@component
+class ElasticsearchBM25Retriever:
+    def __init__(
+        self,
+        *,
+        document_store: ElasticsearchDocumentStore,
+        filters: Optional[Dict[str, Any]] = None,
+        fuzziness: str = "AUTO",
+        top_k: int = 10,
+        scale_score: bool = True,
+    ):
+        if not isinstance(document_store, ElasticsearchDocumentStore):
+            msg = "document_store must be an instance of ElasticsearchDocumentStore"
+            raise ValueError(msg)
+
+        self._document_store = document_store
+        self._filters = filters or {}
+        self._fuzziness = fuzziness
+        self._top_k = top_k
+        self._scale_score = scale_score
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            filters=self._filters,
+            fuzziness=self._fuzziness,
+            top_k=self._top_k,
+            scale_score=self._scale_score,
+            document_store=self._document_store.to_dict(),
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ElasticsearchBM25Retriever":
+        data["init_parameters"]["document_store"] = ElasticsearchDocumentStore.from_dict(
+            data["init_parameters"]["document_store"]
+        )
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=List[Document])
+    def run(self, query: str):
+        docs = self._document_store._bm25_retrieval(
+            query=query,
+            filters=self._filters,
+            fuzziness=self._fuzziness,
+            top_k=self._top_k,
+            scale_score=self._scale_score,
+        )
+        return {"documents": docs}

elasticsearch_haystack/document_store.py

@@ -0,0 +1,308 @@
+# SPDX-FileCopyrightText: 2023-present Silvano Cerza <silvanocerza@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+import logging
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+import numpy as np
+
+# There are no import stubs for elastic_transport and elasticsearch so mypy fails
+from elastic_transport import NodeConfig  # type: ignore[import-not-found]
+from elasticsearch import Elasticsearch, helpers  # type: ignore[import-not-found]
+from haystack.preview import default_from_dict, default_to_dict
+from haystack.preview.dataclasses import Document
+from haystack.preview.document_stores.decorator import document_store
+from haystack.preview.document_stores.errors import DuplicateDocumentError
+from haystack.preview.document_stores.protocols import DuplicatePolicy
+
+from elasticsearch_haystack.filters import _normalize_filters
+
+logger = logging.getLogger(__name__)
+
+Hosts = Union[str, List[Union[str, Mapping[str, Union[str, int]], NodeConfig]]]
+
+# document scores are essentially unbounded and will be scaled to values between 0 and 1 if scale_score is set to
+# True (default). Scaling uses the expit function (inverse of the logit function) after applying a scaling factor
+# (e.g., BM25_SCALING_FACTOR for the bm25_retrieval method).
+# Larger scaling factor decreases scaled scores. For example, an input of 10 is scaled to 0.99 with
+# BM25_SCALING_FACTOR=2 but to 0.78 with BM25_SCALING_FACTOR=8 (default). The defaults were chosen empirically.
+# Increase the default if most unscaled scores are larger than expected (>30) and otherwise would incorrectly
+# all be mapped to scores ~1.
+BM25_SCALING_FACTOR = 8
+
+
+@document_store
+class ElasticsearchDocumentStore:
+    def __init__(self, *, hosts: Optional[Hosts] = None, index: str = "default", **kwargs):
+        """
+        Creates a new ElasticsearchDocumentStore instance.
+
+        For more information on connection parameters, see the official Elasticsearch documentation:
+        https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/connecting.html
+
+        For the full list of supported kwargs, see the official Elasticsearch reference:
+        https://elasticsearch-py.readthedocs.io/en/stable/api.html#module-elasticsearch
+
+        :param hosts: List of hosts running the Elasticsearch client. Defaults to None
+        :param index: Name of index in Elasticsearch, if it doesn't exist it will be created. Defaults to "default"
+        :param **kwargs: Optional arguments that ``Elasticsearch`` takes.
+        """
+        self._hosts = hosts
+        self._client = Elasticsearch(hosts, **kwargs)
+        self._index = index
+        self._kwargs = kwargs
+
+        # Check client connection, this will raise if not connected
+        self._client.info()
+
+        # Create the index if it doesn't exist
+        if not self._client.indices.exists(index=index):
+            self._client.indices.create(index=index)
+
+    def to_dict(self) -> Dict[str, Any]:
+        # This is not the best solution to serialise this class but is the fastest to implement.
+        # Not all kwargs types can be serialised to text so this can fail. We must serialise each
+        # type explicitly to handle this properly.
+        return default_to_dict(
+            self,
+            hosts=self._hosts,
+            index=self._index,
+            **self._kwargs,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ElasticsearchDocumentStore":
+        return default_from_dict(cls, data)
+
+    def count_documents(self) -> int:
+        """
+        Returns how many documents are present in the document store.
+        """
+        return self._client.count(index=self._index)["count"]
+
+    def filter_documents(self, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+        """
+        Returns the documents that match the filters provided.
+
+        Filters are defined as nested dictionaries. The keys of the dictionaries can be a logical operator (`"$and"`,
+        `"$or"`, `"$not"`), a comparison operator (`"$eq"`, `$ne`, `"$in"`, `$nin`, `"$gt"`, `"$gte"`, `"$lt"`,
+        `"$lte"`) or a metadata field name.
+
+        Logical operator keys take a dictionary of metadata field names and/or logical operators as value. Metadata
+        field names take a dictionary of comparison operators as value. Comparison operator keys take a single value or
+        (in case of `"$in"`) a list of values as value. If no logical operator is provided, `"$and"` is used as default
+        operation. If no comparison operator is provided, `"$eq"` (or `"$in"` if the comparison value is a list) is used
+        as default operation.
+
+        Example:
+
+        ```python
+        filters = {
+            "$and": {
+                "type": {"$eq": "article"},
+                "date": {"$gte": "2015-01-01", "$lt": "2021-01-01"},
+                "rating": {"$gte": 3},
+                "$or": {
+                    "genre": {"$in": ["economy", "politics"]},
+                    "publisher": {"$eq": "nytimes"}
+                }
+            }
+        }
+        # or simpler using default operators
+        filters = {
+            "type": "article",
+            "date": {"$gte": "2015-01-01", "$lt": "2021-01-01"},
+            "rating": {"$gte": 3},
+            "$or": {
+                "genre": ["economy", "politics"],
+                "publisher": "nytimes"
+            }
+        }
+        ```
+
+        To use the same logical operator multiple times on the same level, logical operators can take a list of
+        dictionaries as value.
+
+        Example:
+
+        ```python
+        filters = {
+            "$or": [
+                {
+                    "$and": {
+                        "Type": "News Paper",
+                        "Date": {
+                            "$lt": "2019-01-01"
+                        }
+                    }
+                },
+                {
+                    "$and": {
+                        "Type": "Blog Post",
+                        "Date": {
+                            "$gte": "2019-01-01"
+                        }
+                    }
+                }
+            ]
+        }
+        ```
+
+        :param filters: the filters to apply to the document list.
+        :return: a list of Documents that match the given filters.
+        """
+        query = {"bool": {"filter": _normalize_filters(filters)}} if filters else None
+
+        documents: List[Document] = []
+        from_ = 0
+        # Handle pagination
+        while True:
+            res = self._client.search(
+                index=self._index,
+                query=query,
+                from_=from_,
+            )
+            documents.extend(self._deserialize_document(hit) for hit in res["hits"]["hits"])
+            from_ = len(documents)
+            if from_ >= res["hits"]["total"]["value"]:
+                break
+        return documents
+
+    def write_documents(self, documents: List[Document], policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> None:
+        """
+        Writes (or overwrites) documents into the store.
+
+        :param documents: a list of documents.
+        :param policy: documents with the same ID count as duplicates. When duplicates are met,
+            the store can:
+             - skip: keep the existing document and ignore the new one.
+             - overwrite: remove the old document and write the new one.
+             - fail: an error is raised
+        :raises DuplicateDocumentError: Exception trigger on duplicate document if `policy=DuplicatePolicy.FAIL`
+        :return: None
+        """
+        if len(documents) > 0:
+            if not isinstance(documents[0], Document):
+                msg = "param 'documents' must contain a list of objects of type Document"
+                raise ValueError(msg)
+
+        action = "index" if policy == DuplicatePolicy.OVERWRITE else "create"
+        _, errors = helpers.bulk(
+            client=self._client,
+            actions=(
+                {
+                    "_op_type": action,
+                    "_id": doc.id,
+                    "_source": doc.to_dict(),
+                }
+                for doc in documents
+            ),
+            refresh="wait_for",
+            index=self._index,
+            raise_on_error=False,
+        )
+        if errors and policy == DuplicatePolicy.FAIL:
+            # TODO: Handle errors in a better way, we're assuming that all errors
+            # are related to duplicate documents but that could be very well be wrong.
+
+            # mypy complains that `errors`` could be either `int` or a `list` of `dict`s.
+            # Since the type depends on the parameters passed to `helpers.bulk()`` we know
+            # for sure that it will be a `list`.
+            ids = ", ".join(e["create"]["_id"] for e in errors)  # type: ignore[union-attr]
+            msg = f"IDs '{ids}' already exist in the document store."
+            raise DuplicateDocumentError(msg)
+
+    def _deserialize_document(self, hit: Dict[str, Any]) -> Document:
+        """
+        Creates a Document from the search hit provided.
+        This is mostly useful in self.filter_documents().
+        """
+        data = hit["_source"]
+
+        if "highlight" in hit:
+            data["metadata"]["highlighted"] = hit["highlight"]
+        data["score"] = hit["_score"]
+
+        return Document.from_dict(data)
+
+    def delete_documents(self, document_ids: List[str]) -> None:
+        """
+        Deletes all documents with a matching document_ids from the document store.
+
+        :param object_ids: the object_ids to delete
+        """
+
+        #
+        helpers.bulk(
+            client=self._client,
+            actions=({"_op_type": "delete", "_id": id_} for id_ in document_ids),
+            refresh="wait_for",
+            index=self._index,
+            raise_on_error=False,
+        )
+
+    def _bm25_retrieval(
+        self,
+        query: str,
+        *,
+        filters: Optional[Dict[str, Any]] = None,
+        fuzziness: str = "AUTO",
+        top_k: int = 10,
+        scale_score: bool = True,
+    ) -> List[Document]:
+        """
+        Elasticsearch by defaults uses BM25 search algorithm.
+        Even though this method is called `bm25_retrieval` it searches for `query`
+        using the search algorithm `_client` was configured with.
+
+        This method is not mean to be part of the public interface of
+        `ElasticsearchDocumentStore` nor called directly.
+        `ElasticsearchBM25Retriever` uses this method directly and is the public interface for it.
+
+        `query` must be a non empty string, otherwise a `ValueError` will be raised.
+
+        :param query: String to search in saved Documents' text.
+        :param filters: Filters applied to the retrieved Documents, for more info
+                        see `ElasticsearchDocumentStore.filter_documents`, defaults to None
+        :param fuzziness: Fuzziness parameter passed to Elasticsearch, defaults to "AUTO".
+                          see the official documentation for valid values:
+                          https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness
+        :param top_k: Maximum number of Documents to return, defaults to 10
+        :param scale_score: If `True` scales the Document`s scores between 0 and 1, defaults to True
+        :raises ValueError: If `query` is an empty string
+        :return: List of Document that match `query`
+        """
+
+        if not query:
+            msg = "query must be a non empty string"
+            raise ValueError(msg)
+
+        body: Dict[str, Any] = {
+            "size": top_k,
+            "query": {
+                "bool": {
+                    "must": [
+                        {
+                            "multi_match": {
+                                "query": query,
+                                "fuzziness": fuzziness,
+                                "type": "most_fields",
+                                "operator": "AND",
+                            }
+                        }
+                    ]
+                }
+            },
+        }
+
+        if filters:
+            body["query"]["bool"]["filter"] = _normalize_filters(filters)
+
+        res = self._client.search(index=self._index, **body)
+
+        docs = []
+        for hit in res["hits"]["hits"]:
+            if scale_score:
+                hit["_score"] = float(1 / (1 + np.exp(-np.asarray(hit["_score"] / BM25_SCALING_FACTOR))))
+            docs.append(self._deserialize_document(hit))
+        return docs

elasticsearch_haystack/filters.py

@@ -0,0 +1,151 @@
+from typing import Any, Dict, List, Union
+
+from haystack.preview.errors import FilterError
+from pandas import DataFrame
+
+
+def _normalize_filters(filters: Union[List[Dict], Dict], logical_condition="") -> Dict[str, Any]:
+    """
+    Converts Haystack filters in ElasticSearch compatible filters.
+    """
+    if not isinstance(filters, dict) and not isinstance(filters, list):
+        msg = "Filters must be either a dictionary or a list"
+        raise FilterError(msg)
+    conditions = []
+    if isinstance(filters, dict):
+        filters = [filters]
+    for filter_ in filters:
+        for operator, value in filter_.items():
+            if operator in ["$not", "$and", "$or"]:
+                # Logical operators
+                conditions.append(_normalize_filters(value, operator))
+            else:
+                # Comparison operators
+                conditions.extend(_parse_comparison(operator, value))
+
+    if len(conditions) > 1:
+        conditions = _normalize_ranges(conditions)
+    else:
+        # mypy is complaining we're assigning a dict to a list of dicts.
+        # We're ok with this as we're returning right after this.
+        conditions = conditions[0]  # type: ignore[assignment]
+
+    if logical_condition == "$not":
+        return {"bool": {"must_not": conditions}}
+    elif logical_condition == "$or":
+        return {"bool": {"should": conditions}}
+
+    # If no logical condition is specified we default to "$and"
+    return {"bool": {"must": conditions}}
+
+
+def _parse_comparison(field: str, comparison: Union[Dict, List, str, float]) -> List:
+    result: List[Dict[str, Any]] = []
+    if isinstance(comparison, dict):
+        for comparator, val in comparison.items():
+            if isinstance(val, DataFrame):
+                # Ruff is complaining we're overriding the loop variable `var`
+                # but we actually want to override it. So we ignore the error.
+                val = val.to_json()  # noqa: PLW2901
+            if comparator == "$eq":
+                if isinstance(val, list):
+                    result.append(
+                        {
+                            "terms_set": {
+                                field: {
+                                    "terms": val,
+                                    "minimum_should_match_script": {
+                                        "source": f"Math.max(params.num_terms, doc['{field}'].size())"
+                                    },
+                                }
+                            }
+                        }
+                    )
+                result.append({"term": {field: val}})
+            elif comparator == "$ne":
+                if isinstance(val, list):
+                    result.append({"bool": {"must_not": {"terms": {field: val}}}})
+                else:
+                    result.append(
+                        {"bool": {"must_not": {"match": {field: {"query": val, "minimum_should_match": "100%"}}}}}
+                    )
+            elif comparator == "$in":
+                if not isinstance(val, list):
+                    msg = f"{field}'s value must be a list when using '{comparator}' comparator"
+                    raise FilterError(msg)
+                result.append({"terms": {field: val}})
+            elif comparator == "$nin":
+                if not isinstance(val, list):
+                    msg = f"{field}'s value must be a list when using '{comparator}' comparator"
+                    raise FilterError(msg)
+                result.append({"bool": {"must_not": {"terms": {field: val}}}})
+            elif comparator in ["$gt", "$gte", "$lt", "$lte"]:
+                if not isinstance(val, str) and not isinstance(val, int) and not isinstance(val, float):
+                    msg = f"{field}'s value must be 'str', 'int', 'float' types when using '{comparator}' comparator"
+                    raise FilterError(msg)
+                result.append({"range": {field: {comparator[1:]: val}}})
+            elif comparator in ["$not", "$or"]:
+                if isinstance(val, list):
+                    # This handles corner cases like this:
+                    # `{"name": {"$or": [{"$eq": "name_0"}, {"$eq": "name_1"}]}}`
+                    # If we don't handle it like this we'd lose the "name" field and the
+                    # generated query would be wrong and return unexpected results.
+                    comparisons = [_parse_comparison(field, v)[0] for v in val]
+                    if comparator == "$not":
+                        result.append({"bool": {"must_not": comparisons}})
+                    elif comparator == "$or":
+                        result.append({"bool": {"should": comparisons}})
+                else:
+                    result.append(_normalize_filters(val, comparator))
+            elif comparator == "$and" and isinstance(val, list):
+                # We're assuming there are no duplicate items in the list
+                flat_filters = {k: v for d in val for k, v in d.items()}
+                result.extend(_parse_comparison(field, flat_filters))
+            elif comparator == "$and":
+                result.append(_normalize_filters({field: val}, comparator))
+            else:
+                msg = f"Unknown comparator '{comparator}'"
+                raise FilterError(msg)
+    elif isinstance(comparison, list):
+        result.append({"terms": {field: comparison}})
+    elif isinstance(comparison, DataFrame):
+        result.append({"match": {field: {"query": comparison.to_json(), "minimum_should_match": "100%"}}})
+    elif isinstance(comparison, str):
+        # We can't use "term" for text fields as ElasticSearch changes the value of text.
+        # More info here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html#query-dsl-term-query
+        result.append({"match": {field: {"query": comparison, "minimum_should_match": "100%"}}})
+    else:
+        result.append({"term": {field: comparison}})
+    return result
+
+
+def _normalize_ranges(conditions: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Merges range conditions acting on a same field.
+
+    Example usage:
+
+    ```python
+    conditions = [
+        {"range": {"date": {"lt": "2021-01-01"}}},
+        {"range": {"date": {"gte": "2015-01-01"}}},
+    ]
+    conditions = _normalize_ranges(conditions)
+    assert conditions == [
+        {"range": {"date": {"lt": "2021-01-01", "gte": "2015-01-01"}}},
+    ]
+    ```
+    """
+    range_conditions = [next(iter(c["range"].items())) for c in conditions if "range" in c]
+    if range_conditions:
+        conditions = [c for c in conditions if "range" not in c]
+        range_conditions_dict: Dict[str, Any] = {}
+        for field_name, comparison in range_conditions:
+            if field_name not in range_conditions_dict:
+                range_conditions_dict[field_name] = {}
+            range_conditions_dict[field_name].update(comparison)
+
+        for field_name, comparisons in range_conditions_dict.items():
+            conditions.append({"range": {field_name: comparisons}})
+    return conditions

elasticsearch_haystack-0.0.1.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.1
+Name: elasticsearch-haystack
+Version: 0.0.1
+Summary: Haystack 2.x Document Store for ElasticSearch
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/document_stores/elasticsearch#readme
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/document_stores/elasticsearch
+Author-email: Silvano Cerza <silvanocerza@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: elasticsearch<9,>=8
+Requires-Dist: haystack-ai
+Requires-Dist: typing-extensions
+Description-Content-Type: text/markdown
+
+[![test](https://github.com/deepset-ai/haystack-core-integrations/actions/workflows/document_stores_elasticsearch.yml/badge.svg)](https://github.com/deepset-ai/haystack-core-integrations/actions/workflows/document_stores_elasticsearch.yml)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/elasticsearch-haystack.svg)](https://pypi.org/project/elasticsearch-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/elasticsearch-haystack.svg)](https://pypi.org/project/elasticsearch-haystack)
+
+# Elasticsearch Document Store
+
+Document Store for Haystack 2.x, supports ElasticSearch 8.
+
+## Installation
+
+```console
+pip install elasticsearch-haystack
+```
+
+## Testing
+
+To run tests first start a Docker container running ElasticSearch. We provide a utility `docker-compose.yml` for that:
+
+```console
+docker-compose up
+```
+
+Then run tests:
+
+```console
+hatch run test
+```
+
+## License
+
+`elasticsearch-haystack` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.

elasticsearch_haystack-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+elasticsearch_haystack/__about__.py,sha256=IDuWJELihTuNWFXTXOWzkNA5kuxeynOeS0gu2154R6k,140
+elasticsearch_haystack/__init__.py,sha256=rIdDqIKAEAEgQaVw2UCvMynweiCgVGzapZYAWOtdWqM,237
+elasticsearch_haystack/bm25_retriever.py,sha256=pSj2geUWDAHYfcLlexthKWR6F5YGA35e45l9t8Cw3Bw,1997
+elasticsearch_haystack/document_store.py,sha256=YjdwbHDWXgdhyduMvqPKh814ml4gGOXs7R6tUwbMDyE,12470
+elasticsearch_haystack/filters.py,sha256=9kPEVBj2GpXj17vOBUWNCZyb6vC1T_BgDit1SCCFkzw,7069
+elasticsearch_haystack-0.0.1.dist-info/METADATA,sha256=R0aBD9kpCPJCHDzFPkCgnur3Bh-cTunHwf6am24eOM0,2176
+elasticsearch_haystack-0.0.1.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
+elasticsearch_haystack-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+elasticsearch_haystack-0.0.1.dist-info/RECORD,,

elasticsearch_haystack-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.18.0
+Root-Is-Purelib: true
+Tag: py3-none-any

elasticsearch_haystack-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.