Merge pull request #310 from fabric-testbed/amgr

add notebook depicting artifact manager usage via FABlib

fabric_examples/fablib_api/manage_artifacts/manage_artifacts.ipynb

@@ -0,0 +1,269 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d95f0b2d-df12-4956-b049-19ede4d10f7e",
+   "metadata": {},
+   "source": [
+    "# FABRIC Artifact Manager:\n",
+    "\n",
+    "The FABRIC [Artifacts Manager](https://artifacts.fabric-testbed.net) is an invaluable tool for researchers and developers working with the FABRIC testbed. It facilitates the packaging, sharing, and reuse of complete, repeatable FABRIC experiments. By leveraging the FABRIC fablib, users can efficiently manage and interact with experimental artifacts in a streamlined, user-friendly manner. This not only ensures reproducibility but also enhances collaboration by making experiments easily accessible to others.\n",
+    "\n",
+    "## Accessing and Sharing Artifacts\n",
+    "Artifacts managed through the FABRIC Artifacts Manager can be easily accessed by anyone with the appropriate permissions. Whether you're looking to share your experiment with collaborators or make your work publicly available, the Artifact Manager simplifies this process.\n",
+    "\n",
+    "- **Public Artifacts**: Any user can read and download public artifacts directly.\n",
+    "\n",
+    "- **Project-Specific Artifacts**: Artifacts that are tied to specific projects can also be accessed by project members, ensuring that all collaborators have easy access to the data and resources they need.\n",
+    "- **Private**: Only artfiact owner/creator has access to the artifact.\n",
+    "\n",
+    "This setup ensures that your experiments are not only repeatable but also sharable, fostering collaboration and innovation within the research community.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9cb8171b-6b07-4d82-98fb-4d397602995a",
+   "metadata": {},
+   "source": [
+    "## Import the FABlib Library"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7375a04e-91bf-4c03-8093-f9b3d2de8900",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fabrictestbed_extensions.fablib.fablib import FablibManager as fablib_manager\n",
+    "\n",
+    "fablib = fablib_manager()\n",
+    "\n",
+    "fablib.show_config();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e01d15e4-b3fb-47f1-92e7-8077fe96dc35",
+   "metadata": {},
+   "source": [
+    "## List Artifacts\n",
+    "\n",
+    "Enables you to access and view all artifacts, including those you've created, public artifacts, as well as artifacts associated with your project.."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "25866392-ecf4-4bce-910f-40693b7cd1f5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fablib.list_artifacts();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c5e9ce2c-2caf-4dc4-baa8-eb0e5ff0f3f9",
+   "metadata": {},
+   "source": [
+    "## Create a new Artifact\n",
+    "\n",
+    "To create a new artifact, you need to provide several key details to define and manage it effectively:\n",
+    "\n",
+    "- **Title**: Set the artifact_title to give your artifact a clear and descriptive name. For example, \"Test-Artifact\".\n",
+    "\n",
+    "- **Descriptions**:\n",
+    "  - **Short Description**: Provide a brief summary of the artifact's purpose or content. For instance, \"Short Description\".\n",
+    "  - **Long Description**: Include a more detailed explanation of the artifact, outlining its significance and use. For example, \"Long Description\".\n",
+    "\n",
+    "- **Tags**: Use tags to categorize and make the artifact easily searchable. An example tag could be [\"example\"].\n",
+    "\n",
+    "- **Visibility**: Determine who can access the artifact by setting visibility. Options include:\n",
+    "  - **author**: Only accessible to you.\n",
+    "  - **project**: Accessible to others involved in the project.\n",
+    "  - **public**: Accessible to anyone.\n",
+    "\n",
+    "- **Authors**: Specify authors as a list of email addresses for those who contributed to the artifact. If the list is empty, your user token will be used to determine the author."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "753f1f87-8ed7-471d-b257-3b1fd63f3837",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define the artifact details\n",
+    "artifact_title = \"Test-Artifact\"\n",
+    "description_short = \"Short Description\"\n",
+    "description_long = \"Long Description\"\n",
+    "tags = [\"example\"]\n",
+    "visibility = \"project\"  # Options: \"author\", \"project\", \"public\"\n",
+    "authors = []  # List of author email addresses; if empty, use the user's token"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd74c787-3449-4543-b4ad-594a9192cc8e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "artifact = fablib.create_artifact(artifact_title=artifact_title,\n",
+    "                                  description_short=description_short,\n",
+    "                                  description_long=description_long,\n",
+    "                                  tags=tags,\n",
+    "                                  visibility=visibility,\n",
+    "                                  authors=authors)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a5a2b6b0-2802-469d-be9b-2cc630fdee1e",
+   "metadata": {},
+   "source": [
+    "## List the newly created artifact\n",
+    "\n",
+    "We list the newly created artifact by filtering on the title."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f75183a9-cc30-4859-8430-9ac40d430bf6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fablib.list_artifacts(filter_function=lambda x: x['title']==artifact_title);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "39cae1c9-5801-4ea2-af8b-7e5a925b1867",
+   "metadata": {},
+   "source": [
+    "## Upload contents to the artifacts\n",
+    "We will now upload a tar file to the artifact."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d1de12e-2e70-456e-bf65-c6ebd54100c4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file_to_upload = \"./hello_fabric.tgz\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2d222c4d-ba94-417a-a5ac-5d9560a6ca9e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "artifact = fablib.get_artifacts(artifact_title=artifact_title)[0].to_dict()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e3c9067f-17f0-4681-a001-6a0c11148b5c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "upload_response = fablib.upload_file_to_artifact(artifact_id=artifact.get(\"uuid\"), \n",
+    "                                                 file_to_upload=file_to_upload)\n",
+    "\n",
+    "print(f\"Uploaded tar file to artifact: {upload_response}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "deb78c67-e249-46b0-8553-12af9811dce0",
+   "metadata": {},
+   "source": [
+    "## Verify the new contents are available on the artifact\n",
+    "\n",
+    "Artifact versions now start listing here."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8c8839cf-a11c-4d03-b8d0-a30a14e6d9ff",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fablib.list_artifacts(filter_function=lambda x: x['title']==artifact_title);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b5c6e0c1-44dc-468e-b36b-104c13f86570",
+   "metadata": {},
+   "source": [
+    "## Delete an artifact"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6f0fc567-5bdc-4ce3-937e-d883a4b285c3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fablib.delete_artifact(artifact_title=artifact_title);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cc14e0ef-ad98-427e-bbeb-1c62ebf80413",
+   "metadata": {},
+   "source": [
+    "## Verify the deleted artifact is no longer available"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "46da6b40-b3ea-48b6-80e7-5661a284a6ce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fablib.list_artifacts(filter_function=lambda x: x['title']==artifact_title);"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ef5e4328-2e56-420f-897c-55c28a79d324",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

requirements.txt

@@ -1,4 +1,4 @@
-fabrictestbed-extensions==1.7.3
+fabrictestbed-extensions>=1.7.3
 python-dotenv
 ipython==8.12.0
 fabrictestbed-mflib>=1.0.4

start_here.ipynb

@@ -28,7 +28,8 @@
     "- First Experiment\n",
     "    - [Hello, FABRIC](./fabric_examples/fablib_api/hello_fabric/hello_fabric.ipynb): Simple First Slice Example.\n",
     "- Artifact Manager\n",
-    "    - [Explore FABRIC Artifacts](./artifact_manager.ipynb): Managing and Sharing Reproducible Experiments with FABRIC Artifacts Manager.\n",
+    "    - [Explore FABRIC Artifacts](./artifact_manager.ipynb): Download Reproducible Experiments with FABRIC Artifacts Manager.\n",
+    "    - [Manage Artifacts via API](./fabric_examples/fablib_api/manage_artifacts/manage_artifacts.ipynb): Manage Artifacts using FablibManager.\n",
     "\n",
     "## Basic Examples\n",
     "\n",