add to readme, add some marqo integration tests

Author: OwenPendrighElliott

.github/workflows/deploy_docs.yaml

@@ -25,7 +25,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
-        pip install -r requirements.docs.txt
 
     - name: Build documentation
       run: |

.github/workflows/publish.yaml

@@ -0,0 +1,31 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x' 
+
+      - name: Install dependencies
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

README.md

@@ -16,6 +16,11 @@ To get started, you need to run the Marqo container:
 docker run --name marqo -it -p 8882:8882 marqoai/marqo:latest
 ```
 
+Install the required dependencies:
+```bash
+pip install -r requirements.txt
+```
+
 Then, install the marqo-instantapi package:
 ```bash
 pip install .
@@ -32,20 +37,35 @@ INSTANTAPI_KEY=your_instantapi_key
 Then, run the example script:
 
 ```bash
-pip install python-dotenv
 python example.py
 ```
 
 ## Creating documentation
 
-To create documentation for the package, install the required packages:
+Eun the following command to locally build the documentation:
 
 ```bash
-pip install -r requirements.docs.txt
+sphinx-build -b html docs/source docs/build
 ```
 
-Then, run the following command:
+## Running tests
+
+To run tests use pytest:
 
 ```bash
-sphinx-build -b html docs/source docs/build
+python -m pytest
+```
+
+To run the integration tests as well add the flag `--integration`:
+
+```bash
+python -m pytest --integration
+```
+
+## Formatting code
+
+We use the `black` code formatter. To format the code run:
+
+```bash
+black .
 ```

requirements.docs.txt

@@ -1,3 +1,9 @@
 marqo==3.7.0
 requests
-tldextract==5.1.2
+tldextract==5.1.2
+python-dotenv
+pytest
+sphinx 
+sphinx-rtd-theme 
+sphinx-autodoc-typehints
+black

requirements.txt

@@ -37,6 +37,9 @@ def __init__(
             "filterStringMaxLength": 50,
         }
 
+        self.default_text_model = "hf/snowflake-arctic-embed-m-v1.5"
+        self.default_image_model = "open_clip/ViT-B-16-SigLIP-512/webli"
+
     def create_index(
         self,
         index_name: str,
@@ -63,9 +66,9 @@ def create_index(
 
         if model is None:
             if multimodal:
-                settings["model"] = "open_clip/ViT-B-32/laion2b_s34b_b79k"
+                settings["model"] = self.default_image_model
             else:
-                settings["model"] = "hf/e5-base-v2"
+                settings["model"] = self.default_text_model
 
         settings["treatUrlsAndPointersAsImages"] = multimodal
 
@@ -81,12 +84,15 @@ def create_index(
         self.mq.index(index_name).search(q="")
         return response
 
-    def delete_index(self, index_name: str, confirm: bool = False) -> dict:
+    def delete_index(
+        self, index_name: str, confirm: bool = False, skip_if_not_exists: bool = False
+    ) -> dict:
         """Delete a Marqo index.
 
         Args:
             index_name (str): The name of the index to delete.
             confirm (bool, optional): Automatically confirms the deletion. Defaults to False.
+            skip_if_not_exists (bool, optional): Skip deletion if the index does not exist. Defaults to False.
 
         Returns:
             dict: The deletion response.
@@ -100,7 +106,14 @@ def delete_index(self, index_name: str, confirm: bool = False) -> dict:
             if choice == "n":
                 return {"message": "Deletion cancelled."}
 
-        response = self.mq.delete_index(index_name)
+        if not self._check_index_exists(index_name) and skip_if_not_exists:
+            return {
+                "acknowledged": True,
+                "index": index_name,
+                "message": "Index does not exist, skipping deletion.",
+            }
+
+        response = self.mq.index(index_name).delete()
         return response
 
     def _extract_page_data(

src/marqo_instantapi/marqo_instantapi_adapter.py

@@ -0,0 +1,124 @@
+import pytest
+import marqo
+import hashlib
+from marqo_instantapi import InstantAPIMarqoAdapter
+
+
+@pytest.fixture
+def adapter():
+    return InstantAPIMarqoAdapter()
+
+
+@pytest.fixture
+def mq():
+    return marqo.Client()
+
+
+@pytest.mark.integration
+def test_create_index(adapter: InstantAPIMarqoAdapter):
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+    response = adapter.create_index(
+        "example-index", multimodal=True, skip_if_exists=True
+    )
+    # Expected: {"acknowledged":true, "index":"my-first-index"}
+
+    assert response["acknowledged"] is True
+    assert response["index"] == "example-index"
+
+
+@pytest.mark.integration
+def test_error_if_exists(adapter: InstantAPIMarqoAdapter):
+    adapter.create_index("example-index", multimodal=True, skip_if_exists=True)
+    with pytest.raises(Exception):
+        adapter.create_index("example-index", multimodal=True, skip_if_exists=False)
+
+
+@pytest.mark.integration
+def test_error_if_not_exists(adapter: InstantAPIMarqoAdapter):
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+    with pytest.raises(Exception):
+        response = adapter.delete_index(
+            "example-index", confirm=True, skip_if_not_exists=False
+        )
+        print(response)
+
+
+@pytest.mark.integration
+def test_check_exists(adapter: InstantAPIMarqoAdapter):
+    adapter.create_index("example-index", multimodal=True, skip_if_exists=True)
+    assert adapter._check_index_exists("example-index") is True
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+    assert adapter._check_index_exists("example-index") is False
+
+
+@pytest.mark.integration
+def test_check_modality(adapter: InstantAPIMarqoAdapter):
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+    adapter.create_index("example-index", multimodal=True)
+    assert adapter._check_index_can_use_images("example-index") is True
+    adapter.delete_index("example-index", confirm=True)
+
+    adapter.create_index("example-index", multimodal=False)
+    assert adapter._check_index_can_use_images("example-index") is False
+    adapter.delete_index("example-index", confirm=True)
+
+
+@pytest.mark.integration
+def test_search_index(adapter: InstantAPIMarqoAdapter, mq: marqo.Client):
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+    adapter.create_index("example-index", multimodal=False)
+
+    response = mq.index("example-index").add_documents(
+        [
+            {"title": "Hello, World!", "content": "This is a test document."},
+            {"title": "Goodbye, World!", "content": "This is another test document."},
+        ],
+        tensor_fields=["title"],
+    )
+
+    assert not response["errors"]
+
+    search_results = adapter.search(
+        q="hello",
+        index_name="example-index",
+    )
+
+    assert len(search_results["hits"]) == 2
+    assert search_results["hits"][0]["title"] == "Hello, World!"
+    assert search_results["hits"][1]["title"] == "Goodbye, World!"
+
+    adapter.delete_index("example-index", confirm=True)
+
+
+@pytest.mark.integration
+def text_add_documents(adapter: InstantAPIMarqoAdapter):
+    def patched_extract_page_data(
+        self, webpage_url, api_method_name, api_response_structure
+    ):
+        return {"title": "Hello, World!", "content": "This is a test document."}
+
+    adapter._extract_page_data = patched_extract_page_data
+
+    adapter.delete_index("example-index", confirm=True, skip_if_not_exists=True)
+
+    adapter.create_index("example-index", multimodal=False)
+
+    schema = {
+        "title": "the title of the page",
+        "content": "text content summarising the page",
+    }
+
+    response = adapter.add_documents(
+        webpage_urls=["https://example.com"],
+        index_name="example-index",
+        api_response_structure=schema,
+        api_method_name="getPageSummary",
+        text_fields_to_index=["title", "content"],
+    )
+
+    url_md5 = hashlib.md5("https://example.com".encode()).hexdigest()
+
+    response_ids = [doc["url_md5"] for doc in response]
+
+    assert len(response_ids) == 1
+    assert response_ids[0] == url_md5