diff --git a/docs/index.md b/docs/index.md index a06f429..e8f8963 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,11 +26,13 @@ sections_readme/citation vuegen_basic_case_study vuegen_basic_case_study_configfile -vuegen_case_study_earth_microbiome -vuegen_case_study_earth_microbiome_configfile +vuegen_earth_microbiome_case_study +vuegen_earth_microbiome_case_study_configfile example_report -vuegen_APICall_configfile -vuegen_Chatbot_configfile +vuegen_apicall_case_study +vuegen_apicall_case_study_configfile +vuegen_chatbot_case_study +vuegen_chatbot_case_study_configfile ``` ```{toctree} diff --git a/docs/vuegen_apicall_case_study.ipynb b/docs/vuegen_apicall_case_study.ipynb new file mode 100644 index 0000000..387fefd --- /dev/null +++ b/docs/vuegen_apicall_case_study.ipynb @@ -0,0 +1,557 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "e1b731a5", + "metadata": {}, + "source": [ + "# APICall Case Study - Notebook\n", + "\n", + "[![Open In Colab][colab_badge]][colab_link]\n", + "\n", + "**VueGen** is a tool that automates the creation of **reports** from bioinformatics outputs, allowing researchers with minimal coding experience to communicate their results effectively. An overview of the VueGen workflow is shown below:\n", + "\n", + "![Vuegen graphical abstarct][abstractfig_vuegen]\n", + "\n", + "This case study focuses on the `APICall` component, which enables interaction with external APIs by using HTTP methods such as **GET** and **POST**. The retrieved data is displayed in the report, allowing users to integrate external data sources into their anlyses. This component is restricted to **Streamlit** reports.\n", + "\n", + "For general VueGen usage examples, see the [predefined directory][basic_notebook] and [earth microbiome][emp_notebook] case study notebooks.\n", + "\n", + "## Notebook structure\n", + "\n", + "First, we will set up the work environment by installing the necessary packages and importing the required libraries. Next, we will create `APICall` components with different HTTP methods. Finally, we will create a Streamlit report with sections for the `APICall` components with the different HTTP methods.\n", + "\n", + "0. [Work environment setup](#0-work-environment-setup)\n", + "1. [APICall component](#1-apicall)\n", + "2. [Streamlit report generation](#3-streamlit-report)\n", + "\n", + "## Credits and Contributors\n", + "- This notebook was created by Sebastián Ayala-Ruano under the supervision of Henry Webel and Alberto Santos, head of the [Multiomics Network Analytics Group (MoNA)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain].\n", + "- You can find more details about the project in this [GitHub repository][githubrepo].\n", + "- Part of the code from the APICall section was adapated from this [blog post][apicall-blog].\n", + "\n", + "[colab_badge]: https://colab.research.google.com/assets/colab-badge.svg\n", + "[colab_link]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_apicall_case_study.ipynb\n", + "[abstractfig_vuegen]: https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_graph_abstract.png\n", + "[Mona]: https://multiomics-analytics-group.github.io/\n", + "[Biosustain]: https://www.biosustain.dtu.dk/\n", + "[githubrepo]: https://github.com/Multiomics-Analytics-Group/vuegen\n", + "[emp_notebook]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_case_study_earth_microbiome.ipynb\n", + "[basic_notebook]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_basic_case_study.ipynb\n", + "[ollama_chat]: https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion\n", + "[apicall-blog]: https://realpython.com/api-integration-in-python" + ] + }, + { + "cell_type": "markdown", + "id": "008961f3", + "metadata": {}, + "source": [ + "## 0. Work environment setup" + ] + }, + { + "cell_type": "markdown", + "id": "1696fe2d", + "metadata": {}, + "source": [ + "### 0.1. Installing libraries and creating global variables for platform and working directory\n", + "\n", + "To run this notebook locally, you should create a virtual environment with the required libraries. If you are running this notebook on Google Colab, everything should be set." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "800d7d84", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [], + "source": [ + "# Vuegen library\n", + "%pip install vuegen" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "d2328784", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "import os\n", + "\n", + "IN_COLAB = \"COLAB_GPU\" in os.environ" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3bb410ae", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "# Optional library to launch a streamlit app from colab\n", + "if IN_COLAB:\n", + " !npm install localtunnel" + ] + }, + { + "cell_type": "markdown", + "id": "2bc69ee8", + "metadata": {}, + "source": [ + "### 0.2. Importing libraries" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e4cd087d", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "# Imports\n", + "import yaml\n", + "from vuegen import report_generator\n", + "\n", + "if IN_COLAB:\n", + " import urllib" + ] + }, + { + "cell_type": "markdown", + "id": "6f92ab0c", + "metadata": {}, + "source": [ + "### 0.3. Helper functions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f96059ad", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "def save_yaml_config(config, path):\n", + " def multiline_str_handler(dumper, data):\n", + " if \"\\n\" in data:\n", + " return dumper.represent_scalar(\n", + " \"tag:yaml.org,2002:str\", data.strip() + \"\\n\", style=\"|\"\n", + " )\n", + " return dumper.represent_scalar(\"tag:yaml.org,2002:str\", data)\n", + "\n", + " yaml.add_representer(str, multiline_str_handler)\n", + "\n", + " with open(path, \"w\") as f:\n", + " yaml.dump(config, f, sort_keys=False, default_flow_style=False)" + ] + }, + { + "cell_type": "markdown", + "id": "bab8db9a", + "metadata": {}, + "source": [ + "## 1. APICall component\n", + "\n", + "To test the different HTTP methods of the `APICall` component, we will use the [JSONPlaceholder API][jsonplaceholder] as a mock API. This API provides fake data for testing and prototyping.\n", + "\n", + "First, we create a basic config file for the report with general information like the title and description. Then, we create an `APICall` component for each HTTP method: `GET`, `POST`, `PUT`, and `DELETE`. Each component will interact with the **JSONPlaceholder API** and display the results in the report.\n", + "\n", + "[jsonplaceholder]: https://jsonplaceholder.typicode.com/" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "10d17c1a", + "metadata": {}, + "outputs": [], + "source": [ + "# Let's create a dictionary with a minimal config\n", + "config = {\n", + " \"report\": {\n", + " \"title\": \"VueGen APICall Case Study\",\n", + " \"description\": \"This report demonstrates how to use the apicall component in VueGen\",\n", + " },\n", + " \"sections\": [\n", + " {\n", + " \"title\": \"API Examples\",\n", + " \"subsections\": [{\"title\": \"Basic HTTP Methods\", \"components\": []}],\n", + " }\n", + " ],\n", + "}" + ] + }, + { + "cell_type": "markdown", + "id": "89dc2d13", + "metadata": {}, + "source": [ + "### 1.1. GET Request\n", + "\n", + "The `GET` method retrieves data from an API endpoint. Below, we configure a simple `GET` request to fetch a **todo item** from **JSONPlaceholder API**." + ] + }, + { + "cell_type": "code", + "execution_count": 77, + "id": "106e0d4e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ GET request added.\n" + ] + } + ], + "source": [ + "get_component = {\n", + " \"title\": \"GET request\",\n", + " \"component_type\": \"apicall\",\n", + " \"api_url\": \"https://jsonplaceholder.typicode.com/todos/1\",\n", + " \"method\": \"GET\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(get_component)\n", + "print(\"✅ GET request added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "3813f7fe", + "metadata": {}, + "source": [ + "### 1.2. POST Request\n", + "\n", + "The `POST` method sends new data to an API. Here we simulate adding a new **todo item**." + ] + }, + { + "cell_type": "code", + "execution_count": 78, + "id": "e19e0e02", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ POST request added.\n" + ] + } + ], + "source": [ + "post_component = {\n", + " \"title\": \"POST request\",\n", + " \"component_type\": \"apicall\",\n", + " \"api_url\": \"https://jsonplaceholder.typicode.com/todos\",\n", + " \"method\": \"POST\",\n", + " \"request_body\": \"\"\"{\n", + " \"userId\": 1,\n", + " \"title\": \"Go running\",\n", + " \"completed\": false\n", + "}\"\"\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(post_component)\n", + "print(\"✅ POST request added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "c9d8ef49", + "metadata": {}, + "source": [ + "### 1.3. PUT Request\n", + "\n", + "The `PUT` method replaces an existing resource with new data. Here we update a **todo item** completely." + ] + }, + { + "cell_type": "code", + "execution_count": 79, + "id": "c52ec631", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ PUT request added.\n" + ] + } + ], + "source": [ + "put_component = {\n", + " \"title\": \"PUT request\",\n", + " \"component_type\": \"apicall\",\n", + " \"api_url\": \"https://jsonplaceholder.typicode.com/todos/10\",\n", + " \"method\": \"PUT\",\n", + " \"request_body\": \"\"\"\n", + "{\n", + " \"userId\": 1,\n", + " \"title\": \"Play the guitar\",\n", + " \"completed\": true\n", + "}\n", + "\"\"\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(put_component)\n", + "save_yaml_config(config, \"apicall_config.yaml\")\n", + "print(\"✅ PUT request added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "87f16212", + "metadata": {}, + "source": [ + "### 1.4. PATCH Request\n", + "\n", + "The `PATCH` method updates part of an existing resource. Below, we only update the title of a **todo item**." + ] + }, + { + "cell_type": "code", + "execution_count": 80, + "id": "07fd3599", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ PATCH request added.\n" + ] + } + ], + "source": [ + "patch_component = {\n", + " \"title\": \"PATCH request\",\n", + " \"component_type\": \"apicall\",\n", + " \"api_url\": \"https://jsonplaceholder.typicode.com/todos/10\",\n", + " \"method\": \"PATCH\",\n", + " \"request_body\": \"\"\"\n", + "{\n", + " \"title\": \"Go for a hike\"\n", + "}\n", + "\"\"\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(patch_component)\n", + "print(\"✅ PATCH request added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "fe6781d0", + "metadata": {}, + "source": [ + "### 1.5. DELETE Request\n", + "\n", + "The `DELETE` method removes a resource. Here's how to delete a **todo item**." + ] + }, + { + "cell_type": "code", + "execution_count": 81, + "id": "24ba25aa", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ DELETE request added.\n" + ] + } + ], + "source": [ + "delete_component = {\n", + " \"title\": \"DELETE request\",\n", + " \"component_type\": \"apicall\",\n", + " \"api_url\": \"https://jsonplaceholder.typicode.com/todos/10\",\n", + " \"method\": \"DELETE\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(delete_component)\n", + "print(\"✅ DELETE request added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "481ebbbd", + "metadata": {}, + "source": [ + "### 1.6. Save the report config file" + ] + }, + { + "cell_type": "code", + "execution_count": 82, + "id": "86976bc0", + "metadata": {}, + "outputs": [], + "source": [ + "# Save the report config file\n", + "config_path = \"apicall_config.yaml\"\n", + "save_yaml_config(config, config_path)" + ] + }, + { + "cell_type": "markdown", + "id": "b4bf2a40", + "metadata": {}, + "source": [ + "## 2. Streamlit report generation\n", + "\n", + "You now have a complete configuration file with all 5 basic HTTP methods. You can run VueGen with this config to see it in action.\n", + "\n", + "**Note:** To launch the Streamlit web application from Colab, open the generated URL and copy the localtunnel entry point IP into the corresponding field on the opened page. Once submited, you will be redirected to your Streamlit web application." + ] + }, + { + "cell_type": "code", + "execution_count": 45, + "id": "2e165e30", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "[2025-06-12 12:01:35,799] vuegen: INFO - Path to log file: logs/2025-06-12_12-01-35_report.log\n", + "[2025-06-12 12:01:35,804] vuegen: INFO - Report 'VueGen API Call and Chatbot Case Study' initialized with 1 sections.\n", + "[2025-06-12 12:01:35,805] vuegen: INFO - running in a normal Python process\n", + "[2025-06-12 12:01:35,806] vuegen: DEBUG - Generating 'streamlit' report in directory: 'streamlit_report/sections'\n", + "[2025-06-12 12:01:35,807] vuegen: INFO - Output directory already existed: 'streamlit_report/sections'\n", + "[2025-06-12 12:01:35,809] vuegen: INFO - Output directory for static content already existed: 'streamlit_report/static'\n", + "[2025-06-12 12:01:35,810] vuegen: DEBUG - Processing app navigation code.\n", + "[2025-06-12 12:01:35,811] vuegen: DEBUG - Processing home section.\n", + "[2025-06-12 12:01:35,811] vuegen: DEBUG - Home directory already existed: streamlit_report/sections/Home\n", + "[2025-06-12 12:01:35,813] vuegen: INFO - Home page content written to 'streamlit_report/sections/Home/Homepage.py'.\n", + "[2025-06-12 12:01:35,813] vuegen: INFO - Home page added to the report manager content.\n", + "[2025-06-12 12:01:35,814] vuegen: INFO - Created app navigation script: report_manager.py\n", + "[2025-06-12 12:01:35,815] vuegen: INFO - Starting to generate sections for the report.\n", + "[2025-06-12 12:01:35,815] vuegen: INFO - All the scripts to build the Streamlit app are available at streamlit_report/sections\n", + "[2025-06-12 12:01:35,816] vuegen: INFO - To run the Streamlit app, use the following command:\n", + "[2025-06-12 12:01:35,816] vuegen: INFO - streamlit run streamlit_report/sections/report_manager.py\n", + "\n", + "All the scripts to build the Streamlit app are available at: streamlit_report/sections\n", + "\n", + "To run the Streamlit app, use the following command:\n", + "\n", + "\tstreamlit run streamlit_report/sections/report_manager.py\n" + ] + } + ], + "source": [ + "# Generate the report\n", + "report_type = \"streamlit\"\n", + "_ = report_generator.get_report(\n", + " config_path=config_path, report_type=report_type, logger=None\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2983d5c0", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[0m\n", + "\u001b[34m\u001b[1m You can now view your Streamlit app in your browser.\u001b[0m\n", + "\u001b[0m\n", + "\u001b[34m Local URL: \u001b[0m\u001b[1mhttp://localhost:8501\u001b[0m\n", + "\u001b[34m Network URL: \u001b[0m\u001b[1mhttp://192.168.0.231:8501\u001b[0m\n", + "\u001b[0m\n", + "\u001b[34m\u001b[1m For better performance, install the Watchdog module:\u001b[0m\n", + "\n", + " $ xcode-select --install\n", + " $ pip install watchdog\n", + " \u001b[0m\n", + "\u001b[34m Stopping...\u001b[0m\n" + ] + } + ], + "source": [ + "run_streamlit = False\n", + "# run_streamlit = True # uncomment line to run the streamlit report\n", + "# Launch the Streamlit report depneding on the platform\n", + "if not IN_COLAB and run_streamlit:\n", + " !streamlit run streamlit_report/sections/report_manager.py\n", + "elif run_streamlit:\n", + " # see: https://discuss.streamlit.io/t/how-to-launch-streamlit-app-from-google-colab-notebook/42399\n", + " print(\n", + " \"Password/Enpoint IP for localtunnel is:\",\n", + " urllib.request.urlopen(\"https://ipv4.icanhazip.com\")\n", + " .read()\n", + " .decode(\"utf8\")\n", + " .strip(\"\\n\"),\n", + " )\n", + " # Run the Streamlit app in the background\n", + " !streamlit run streamlit_report/sections/report_manager.py --server.address=localhost &>/content/logs.txt &\n", + " # Expose the Streamlit app on port 8501\n", + " !npx localtunnel --port 8501 --subdomain vuegen-demo\n", + "else:\n", + " print(\"Streamlit report not executed, set run_streamlit to True to run the report\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vuegen-pip", + "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.12.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/vuegen_APICall_configfile.md b/docs/vuegen_apicall_case_study_configfile.md similarity index 100% rename from docs/vuegen_APICall_configfile.md rename to docs/vuegen_apicall_case_study_configfile.md diff --git a/docs/vuegen_chatbot_case_study.ipynb b/docs/vuegen_chatbot_case_study.ipynb new file mode 100644 index 0000000..7bc8bb7 --- /dev/null +++ b/docs/vuegen_chatbot_case_study.ipynb @@ -0,0 +1,405 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "e1b731a5", + "metadata": {}, + "source": [ + "# Chatbot Case Study - Notebook\n", + "\n", + "[![Open In Colab][colab_badge]][colab_link]\n", + "\n", + "**VueGen** is a tool that automates the creation of **reports** from bioinformatics outputs, allowing researchers with minimal coding experience to communicate their results effectively. An overview of the VueGen workflow is shown below:\n", + "\n", + "![Vuegen graphical abstarct][abstractfig_vuegen]\n", + "\n", + "This case study focuses on two the `Chatbot` component, which allows users to interact with a large language model (LLM) endpoint and display the results in a chat interface. It supports two API interaction modes:\n", + "\n", + "- **Standard prompt-response API:** sends a prompt and expects a structured JSON response.\n", + "- **Ollama-style streaming chat completion:** Uses Ollama’s [/api/chat endpoint][ollama_chat] to stream responses from models like `llama3`, `deepsek`, or `mistral`.\n", + "\n", + "For general VueGen usage examples, see the [predefined directory][basic_notebook] and [earth microbiome][emp_notebook] case study notebooks.\n", + "\n", + "## Notebook structure\n", + "\n", + "First, we will set up the work environment by installing the necessary packages and importing the required libraries. Next, we will create `APICall` components with different HTTP methods. We will then create a `Chatbot` component using the Ollama-style streaming mode. Finally, we will create a Streamlit report with sections for the `APICall` and `Chatbot` components.\n", + "\n", + "0. [Work environment setup](#0-work-environment-setup)\n", + "1. [Chatbot component](#2-chatbot)\n", + "2. [Streamlit report generation](#3-streamlit-report)\n", + "\n", + "## Credits and Contributors\n", + "- This notebook was created by Sebastián Ayala-Ruano under the supervision of Henry Webel and Alberto Santos, head of the [Multiomics Network Analytics Group (MoNA)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain].\n", + "- You can find more details about the project in this [GitHub repository][githubrepo].\n", + "\n", + "[colab_badge]: https://colab.research.google.com/assets/colab-badge.svg\n", + "[colab_link]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_chatbot_case_study.ipynb\n", + "[abstractfig_vuegen]: https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_graph_abstract.png\n", + "[Mona]: https://multiomics-analytics-group.github.io/\n", + "[Biosustain]: https://www.biosustain.dtu.dk/\n", + "[githubrepo]: https://github.com/Multiomics-Analytics-Group/vuegen\n", + "[emp_notebook]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_case_study_earth_microbiome.ipynb\n", + "[basic_notebook]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_basic_case_study.ipynb\n", + "[ollama_chat]: https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion" + ] + }, + { + "cell_type": "markdown", + "id": "008961f3", + "metadata": {}, + "source": [ + "## 0. Work environment setup" + ] + }, + { + "cell_type": "markdown", + "id": "1696fe2d", + "metadata": {}, + "source": [ + "### 0.1. Installing libraries and creating global variables for platform and working directory\n", + "\n", + "To run this notebook locally, you should create a virtual environment with the required libraries. If you are running this notebook on Google Colab, everything should be set." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "800d7d84", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [], + "source": [ + "# Vuegen library\n", + "%pip install vuegen" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "d2328784", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "import os\n", + "\n", + "IN_COLAB = \"COLAB_GPU\" in os.environ" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3bb410ae", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "# Optional library to launch a streamlit app from colab\n", + "if IN_COLAB:\n", + " !npm install localtunnel" + ] + }, + { + "cell_type": "markdown", + "id": "2bc69ee8", + "metadata": {}, + "source": [ + "### 0.2. Importing libraries" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "e4cd087d", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "# Imports\n", + "import yaml\n", + "from vuegen import report_generator\n", + "\n", + "if IN_COLAB:\n", + " import urllib" + ] + }, + { + "cell_type": "markdown", + "id": "6f92ab0c", + "metadata": {}, + "source": [ + "### 0.3. Helper functions" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "f96059ad", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "def save_yaml_config(config, path):\n", + " with open(path, \"w\") as f:\n", + " yaml.dump(config, f, sort_keys=False, default_flow_style=False)" + ] + }, + { + "cell_type": "markdown", + "id": "bab8db9a", + "metadata": {}, + "source": [ + "## 1. Chatbot component\n", + "\n", + "Before creating the configuration file for the `ChatBot` component, there should be a working **API endpoint** that can be used to test the component. In this case, we will use the **Ollama-style streaming chat completion API**." + ] + }, + { + "cell_type": "markdown", + "id": "79f951d2", + "metadata": {}, + "source": [ + "### 1.1. Setting up the API endpoint \n", + "\n", + "You should have the **Ollama server** running locally or on a remote server. If you have not installed this software, you can download it from the [Ollama website][ollama_website] and follow the installation instructions.\n", + "\n", + "You can check the available models [here](https://ollama.com/search). After selecting a model, you can use the `run` command to start the Ollama server with the desired model. For example, to run the `llama3` model, you can use:\n", + "\n", + "```bash\n", + "ollama run llama3\n", + "```\n", + "\n", + "And now the API endpoint will be available at `http://localhost:11434/api/chat`.\n", + "\n", + "[ollama_website]: https://ollama.com/\n" + ] + }, + { + "cell_type": "markdown", + "id": "66585969", + "metadata": {}, + "source": [ + "### 1.2. Creating the configuration file for the ChatBot component \n", + "\n", + "First, we create a basic configuration file for the report with general information like the title and description. Then, we create a `ChatBot` component that uses **API endpoint** we set up in the previous step. This component will allow us to interact with a **large language model (LLM) endpoint** and display the results in a chat interface." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "10d17c1a", + "metadata": {}, + "outputs": [], + "source": [ + "# Let's create a dictionary with a minimal config\n", + "config = {\n", + " \"report\": {\n", + " \"title\": \"VueGen Chatbot Case Study\",\n", + " \"description\": \"This report demonstrates how to use the chatbot component in VueGen\",\n", + " },\n", + " \"sections\": [\n", + " {\n", + " \"title\": \"Chatbot Example\",\n", + " \"subsections\": [\n", + " {\"title\": \"Ollama-style streaming chatbot\", \"components\": []}\n", + " ],\n", + " }\n", + " ],\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "106e0d4e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "✅ ChatBot component added.\n" + ] + } + ], + "source": [ + "chatbot_component = {\n", + " \"title\": \"ChatBot Component\",\n", + " \"component_type\": \"chatbot\",\n", + " \"api_url\": \"http://localhost:11434/api/chat\",\n", + " \"model\": \"llama3.2\",\n", + "}\n", + "\n", + "config[\"sections\"][0][\"subsections\"][0][\"components\"].append(chatbot_component)\n", + "print(\"✅ ChatBot component added.\")" + ] + }, + { + "cell_type": "markdown", + "id": "481ebbbd", + "metadata": {}, + "source": [ + "### 1.3. Save the report config file" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "86976bc0", + "metadata": {}, + "outputs": [], + "source": [ + "# Save the report config file\n", + "config_path = \"chatbot_config.yaml\"\n", + "save_yaml_config(config, config_path)" + ] + }, + { + "cell_type": "markdown", + "id": "b4bf2a40", + "metadata": {}, + "source": [ + "## 2. Streamlit report generation\n", + "\n", + "You now have a complete configuration file for the chatbot. You can run VueGen with this config to see it in action.\n", + "\n", + "**Note:** To launch the Streamlit web application from Colab, open the generated URL and copy the localtunnel entry point IP into the corresponding field on the opened page. Once submited, you will be redirected to your Streamlit web application." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "2e165e30", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "[2025-06-12 16:39:52,894] vuegen: INFO - Path to log file: logs/2025-06-12_16-39-52_report.log\n", + "[2025-06-12 16:39:52,898] vuegen: INFO - Report 'VueGen Chatbot Case Study' initialized with 1 sections.\n", + "[2025-06-12 16:39:52,899] vuegen: INFO - running in a normal Python process\n", + "[2025-06-12 16:39:52,900] vuegen: DEBUG - Generating 'streamlit' report in directory: 'streamlit_report/sections'\n", + "[2025-06-12 16:39:52,901] vuegen: INFO - Output directory already existed: 'streamlit_report/sections'\n", + "[2025-06-12 16:39:52,902] vuegen: INFO - Output directory for static content already existed: 'streamlit_report/static'\n", + "[2025-06-12 16:39:52,903] vuegen: DEBUG - Processing app navigation code.\n", + "[2025-06-12 16:39:52,904] vuegen: DEBUG - Processing home section.\n", + "[2025-06-12 16:39:52,905] vuegen: DEBUG - Home directory already existed: streamlit_report/sections/Home\n", + "[2025-06-12 16:39:52,906] vuegen: INFO - Home page content written to 'streamlit_report/sections/Home/Homepage.py'.\n", + "[2025-06-12 16:39:52,906] vuegen: INFO - Home page added to the report manager content.\n", + "[2025-06-12 16:39:52,907] vuegen: INFO - Created app navigation script: report_manager.py\n", + "[2025-06-12 16:39:52,908] vuegen: INFO - Starting to generate sections for the report.\n", + "[2025-06-12 16:39:52,908] vuegen: INFO - All the scripts to build the Streamlit app are available at streamlit_report/sections\n", + "[2025-06-12 16:39:52,909] vuegen: INFO - To run the Streamlit app, use the following command:\n", + "[2025-06-12 16:39:52,909] vuegen: INFO - streamlit run streamlit_report/sections/report_manager.py\n", + "\n", + "All the scripts to build the Streamlit app are available at: streamlit_report/sections\n", + "\n", + "To run the Streamlit app, use the following command:\n", + "\n", + "\tstreamlit run streamlit_report/sections/report_manager.py\n" + ] + } + ], + "source": [ + "# Generate the report\n", + "report_type = \"streamlit\"\n", + "_ = report_generator.get_report(\n", + " config_path=config_path, report_type=report_type, logger=None\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2983d5c0", + "metadata": { + "tags": [ + "hide-output" + ] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\u001b[0m\n", + "\u001b[34m\u001b[1m You can now view your Streamlit app in your browser.\u001b[0m\n", + "\u001b[0m\n", + "\u001b[34m Local URL: \u001b[0m\u001b[1mhttp://localhost:8501\u001b[0m\n", + "\u001b[34m Network URL: \u001b[0m\u001b[1mhttp://192.168.0.231:8501\u001b[0m\n", + "\u001b[0m\n", + "\u001b[34m\u001b[1m For better performance, install the Watchdog module:\u001b[0m\n", + "\n", + " $ xcode-select --install\n", + " $ pip install watchdog\n", + " \u001b[0m\n", + "\u001b[34m Stopping...\u001b[0m\n" + ] + } + ], + "source": [ + "run_streamlit = False\n", + "# run_streamlit = True # uncomment line to run the streamlit report\n", + "# Launch the Streamlit report depneding on the platform\n", + "if not IN_COLAB and run_streamlit:\n", + " !streamlit run streamlit_report/sections/report_manager.py\n", + "elif run_streamlit:\n", + " # see: https://discuss.streamlit.io/t/how-to-launch-streamlit-app-from-google-colab-notebook/42399\n", + " print(\n", + " \"Password/Enpoint IP for localtunnel is:\",\n", + " urllib.request.urlopen(\"https://ipv4.icanhazip.com\")\n", + " .read()\n", + " .decode(\"utf8\")\n", + " .strip(\"\\n\"),\n", + " )\n", + " # Run the Streamlit app in the background\n", + " !streamlit run streamlit_report/sections/report_manager.py --server.address=localhost &>/content/logs.txt &\n", + " # Expose the Streamlit app on port 8501\n", + " !npx localtunnel --port 8501 --subdomain vuegen-demo\n", + "else:\n", + " print(\"Streamlit report not executed, set run_streamlit to True to run the report\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vuegen-pip", + "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.12.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/vuegen_Chatbot_configfile.md b/docs/vuegen_chatbot_case_study_configfile.md similarity index 100% rename from docs/vuegen_Chatbot_configfile.md rename to docs/vuegen_chatbot_case_study_configfile.md diff --git a/docs/vuegen_case_study_earth_microbiome.ipynb b/docs/vuegen_earth_microbiome_case_study.ipynb similarity index 100% rename from docs/vuegen_case_study_earth_microbiome.ipynb rename to docs/vuegen_earth_microbiome_case_study.ipynb diff --git a/docs/vuegen_case_study_earth_microbiome_configfile.md b/docs/vuegen_earth_microbiome_case_study_configfile.md similarity index 100% rename from docs/vuegen_case_study_earth_microbiome_configfile.md rename to docs/vuegen_earth_microbiome_case_study_configfile.md