Docs (#3)

* setup docs

* add pipeline

* add push request to test the pipeline

* add model for now

* adjust path insert instead of append

* remove recursion in table of content

* adjust docstring

* remove my API (now reset..)

* remove from repo for now

* linting

* remove cname

* only build on new release

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  release:
+    types:
+      - published
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  docs:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install the latest version of rye
+      uses: eifinger/setup-rye@v3
+    - name: Sync dependencies
+      shell: bash -l {0}
+      run: rye sync
+    - name: Build docs
+      shell: bash -l {0}
+      run: rye run docs
+    - name: Upload HTML artificat
+      uses: actions/upload-artifact@v4
+      with:
+        name: DocumentationHTML
+        path: docs/_build/html/
+    - name: Commit to gh-pages
+      run: |
+        git clone https://github.com/ammaraskar/sphinx-action-test.git --branch gh-pages --single-branch gh-pages
+        cp -r docs/_build/html/* gh-pages/
+        cd gh-pages
+        touch .nojekyll
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+        git add .
+        git commit -m "Update documentation" -a || true
+        # The above command will fail if no changes were present
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: gh-pages
+        directory: gh-pages
+        force: true

Dockerfile

@@ -1,7 +1,4 @@
 # https://docs.streamlit.io/deploy/tutorials/docker
-# docker build -t alice-rag-llm .   
-# docker run -p 8501:8501 -e GEMINI_API_TOKEN="AIzaSyA3zVz7txsa4jttqMCAKlKrtPQwXcGb6J8" alice-rag-llm
-
 FROM python:3.12-slim
 
 WORKDIR /app

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/class.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/module.rst

@@ -0,0 +1,62 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :template: class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: module.rst
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api.rst

@@ -0,0 +1,12 @@
+API
+===
+
+Auto-generated summary of the different modules of Alice RAG.
+
+.. autosummary::
+    :toctree: _autosummary
+    :template: module.rst
+    :recursive:
+
+    app
+    store

docs/conf.py

@@ -0,0 +1,38 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+# -- Project information
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+project = "Alice RAG"
+copyright = "2024"
+author = "Philippe Miron"
+
+# -- General configuration
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx_copybutton",
+]
+
+autosummary_generate = True
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output
+html_theme = "sphinx_book_theme"
+html_logo = "logo.webp"
+html_favicon = "favicon.ico"
+html_static_path: list[str] = []
+
+# sphinx-copybutton settings
+copybutton_exclude = ".linenos, .gp"  # don't copy prompts or line numbers

docs/description.rst

@@ -0,0 +1,79 @@
+.. _description:
+
+Description
+===========
+
+This page gives a global overview of the application, its components, and the underlying technologies used to build it. The following sections provide a detailed description of the system's architecture, user interaction, and the AI models employed.
+
+User Interaction
+----------------
+
+Built using `Streamlit <https://streamlit.io/>`_, the interface is designed to be user-friendly, intuitive, and efficient for interacting with the Retrieval-Augmented Generation system. The key components are:
+
+- Chat Window: The primary area where the conversation takes place. This window displays user inputs and the corresponding responses from Gemini in a chat-like format. AI responses are streamed in real-time to enhance user feedback and interaction. A small icon next to the messages makes it easy to distinguish user queries and AI responses.
+
+- Sidebar: Includes the available model that can be used to query the document. The user can select the desired model from the radio button to optimize the performance of the system.
+
+- Input Field: A text box where users can type their questions, commonly referred as prompts.
+
+- Send Button: A button to submit the text entered in the input field. This can be clicked or activated by pressing the Enter key on the keyboard.
+
+Document Retrieval (VectorStore)
+--------------------------------
+
+We utilize `LlamaIndex <https://www.llamaindex.ai/>`_ for ingesting the documents, and creating easily creating the vector store. The embedding model used is `BAAI/bge-small-en-v1.5 <https://huggingface.co/BAAI/bge-small-en-v1.5>`_.
+
+When a user provides a `{query}`, it is appended to the following prefix: `Represent this sentence for searching relevant passages: {query}`, as recommended in `BAAI's documentation <https://model.baai.ac.cn/model-detail/100112#usage>`_.
+
+Note: For this proof of concept, I did not explore many different embedding models. The selected model was chosen based on a recommendation from a RAG tutorial in the `LlamaIndex documentation <https://docs.llamaindex.ai/en/stable/examples/low_level/oss_ingestion_retrieval/>`_. In a real-world scenario, it would be beneficial to benchmark various models to optimize the user experience.
+
+Prompt Generation
+-----------------
+
+We combine results from vector store retrieval with the user's query to generate a prompt for the selected Gemini model.
+
+The prompt was designed based on guidelines provided in the `Gemini documentation <https://model.baai.ac.cn/model-detail/100112#usage>`_ and this insightful article on understanding `RAG <https://medium.com/@saurabhgssingh/understanding-rag-building-a-rag-system-from-scratch-with-gemini-api-b11ad9fc1bf7>`_ architecture.
+
+Specifically, the top relevant passages and the user query are concatenated in the following format:
+
+.. code-block:: python
+
+    def make_rag_prompt(query: str, relevant_passages: list[str]) -> str:
+        """Generate the RAG prompt
+
+        Args:
+            query (str): user query
+            relevant_passages (list[str]): list of relevant passages obtained from the index
+
+        Returns:
+            str: the prompt to pass to the LLM API
+        """
+        escaped_passages = " ".join(
+            passage.replace("'", "").replace('"', "").replace("\n", " ")
+            for passage in relevant_passages
+        )
+
+        prompt = (
+            "You are a helpful and informative bot that answers questions using text from "
+            "the reference passages included below. Be sure to respond in a complete sentence, "
+            "being comprehensive, including all relevant background information. However, you "
+            "are talking to a non-technical audience, so be sure to break down complicated "
+            "concepts and strike a friendly and conversational tone. If the passages are "
+            "irrelevant to the answer, you may ignore them.\n"
+            f"QUESTION: '{query}'\n"
+            f"PASSAGES: '{escaped_passages}'\n\n"
+            "ANSWER:\n"
+        )
+
+        return prompt
+
+Large Language Model
+--------------------
+
+Choices of three models from the Gemini's family are available. The choice of model was simply made because Google offer limited free tier API! The current available models are:
+
+- Gemini 1.0 Pro
+- Gemini 1.5 Pro
+- Gemini 1.5 Flash
+
+The first model is from the previous generation, it is slightly faster but returns simpler and less accurate answer as the newer models. The two latest models are more accurate, in practice would be more expensive, and are slightly slower. The default model is set to `Gemini 1.5 Flash`, which provides fast and versatile performance across diverse variety of tasks. The user can change the model on the left sidebar of the interface to optimize their experience.

docs/index.rst

@@ -0,0 +1,45 @@
+Alice RAG
+=========
+
+Alice Retrieval-Augmented Generation (RAG) is a proof of concept application designed to answer queries about *Alice's Adventures in Wonderland*, Lewis Carroll's timeless classic. This innovative solution leverages the power of modern AI to combine the strengths of retrieval-based and generation-based approaches. By integrating a language model with a customized knowledge store, "Alice RAG" can accurately and efficiently retrieve and generate responses.
+
+This project showcases my ability to implement advanced AI techniques, containerization, CI/CD, documentation, and web-based interaction using `Streamlit <https://streamlit.io/>`_, all while adhering to best practices in software development and deployment.
+
+Alice RAG stands out by utilizing the LlamaIndex framework to create a vector database from *Alice's Adventures in Wonderland*, enabling precise and contextually relevant responses to user queries. The code then employs Gemini models to generate answers based on the retrieved context, ensuring high-quality and accurate responses. The solution is containerized using Docker, ensuring seamless deployment and scalability, and is designed to be cloud-ready, with optional Infrastructure as Code (IaC) scripts for Azure deployment. The project demonstrates a full-stack AI application reflecting my comprehensive skill set in AI engineering, DevOps, and cloud infrastructure management. Through this project, I aim to illustrate my capability to deliver robust, efficient, and user-friendly AI solutions in a professional setting.
+
+Getting started
+---------------
+
+* :doc:`description`
+* :doc:`usage`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Getting started
+
+   description
+   usage
+
+Reference
+---------
+
+* :doc:`api`
+* GitHub_
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+    :caption: Reference
+
+    api
+    GitHub <https://github.com/philippemiron/alice-rag-llm>
+
+.. _github: https://github.com/philippemiron/alice-rag-llm
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd