Merge pull request #12 from VectorInstitute/doc/guidelines

Guidelines and Dockerization of the template

Author: amrit110

.env.example

@@ -0,0 +1,2 @@
+ENV_VARIABLE_ONE=<your_environment_variable_value_one>
+ENV_VARIABLE_TWO=<your_environment_variable_value_two>

.github/workflows/code_checks.yml

@@ -43,12 +43,11 @@ jobs:
         with:
           python-version-file: ".python-version"
 
-      - name: Install the project
-        run: uv sync --all-extras --dev
-
       - name: Install dependencies and check code
         run: |
+          uv venv .venv
           source .venv/bin/activate
+          uv sync --all-extras --dev
           pre-commit run --all-files
 
       - name: pip-audit (gh-action-pip-audit)

.github/workflows/publish.yml

@@ -30,8 +30,12 @@ jobs:
         with:
           python-version-file: ".python-version"
 
-      - name: Install the project
-        run: cd aieng-topic-impl && uv sync --dev
+      - name: Install dependencies
+        run: |
+          cd aieng-topic-impl
+          uv venv .venv
+          source .venv/bin/activate
+          uv sync --all-extras --dev
 
       - name: Build package
         run: cd aieng-topic-impl && source .venv/bin/activate && uv build
@@ -42,10 +46,3 @@ jobs:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}
           packages-dir: aieng-topic-impl/dist/
-
-      - name: Create GitHub Release
-        id: create_release
-        uses: ncipollo/release-action@440c8c1cb0ed28b9f43e4d1d670870f059653174 # v1.16.0
-        with:
-          artifacts: "aieng-topic-impl/dist/*"
-          generateReleaseNotes: true

.github/workflows/unit_tests.yml

@@ -51,11 +51,10 @@ jobs:
         with:
           python-version-file: ".python-version"
 
-      - name: Install the project
-        run: cd aieng-topic-impl && uv sync --all-extras --dev
-
       - name: Install dependencies and check code
         run: |
           cd aieng-topic-impl
+          uv venv .venv
           source .venv/bin/activate
+          uv sync --all-extras --dev
           uv run pytest -m "not integration_test" tests

.gitignore

@@ -22,3 +22,5 @@ wheels/
 
 # ipynb checkpoints
 **.ipynb_checkpoints
+
+.env

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to aieng-template
 
-Thanks for your interest in contributing to the aieng-template-bootcamp!
+Thanks for your interest in contributing to the aieng-template-implementation!
 
 To submit PRs, please fill out the PR template along with the PR. If the PR
 fixes an issue, don't forget to link the PR to the issue!

Dockerfile

@@ -0,0 +1,35 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+EXPOSE 8888
+
+# Install system dependencies
+RUN apt-get update \
+    && apt-get install -y \
+    sudo \
+    curl \
+    git \
+    jq \
+    tar \
+    unzip \
+    ca-certificates \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# !!IMPORTANT!!
+# THIS SECTION SHOULD NOT BE MODIFIED AS
+# IT IS USED TO MAKE THIS IMAGE COMPATIBLE WITH CODER
+#######################################################################
+ARG USER=coder
+RUN useradd --groups sudo --no-create-home --shell /bin/bash ${USER} \
+    && echo "${USER} ALL=(ALL) NOPASSWD:ALL" >/etc/sudoers.d/${USER} \
+    && chmod 0440 /etc/sudoers.d/${USER}
+
+USER ${USER}
+WORKDIR /home/${USER}
+########################################################################
+
+# Copy the code into the container
+COPY --chown=${USER}:${USER} . /home/${USER}/aieng-template-implementation
+
+# Start the container and run the project setup script
+CMD ["bash", "aieng-template-implementation/scripts/setup.sh"]

GUIDELINES.md

@@ -0,0 +1,72 @@
+# GUIDELINES
+
+These guidelines are recommended for anyone creating a repository using this template for building reference implementations.
+
+## Repository Name
+
+Choose a repository name that reflects the main topic of your reference implementations. Avoid generic terms like 'workshop', 'bootcamp', 'reference', or 'implementations'. Instead, use a concise topic name that best describes the content.
+
+**Example:** Use `retrieval-augmented-generation` if your repository contains reference implementations for RAG concepts. Select a single, descriptive topic name for the project.
+
+> **Note:** If you cannot use the recommended naming convention initially, you may start with a different name and update it later.
+
+## Environment Variables
+
+Manage environment variables using a `.env` file and access them in your code with `os.getenv("ENV_VARIABLE", "default-value")`. List all environment-specific variables in a `.env.example` file with placeholder values for easy reference and onboarding.
+
+## Utility Packages
+
+Place all common methods and classes used across implementations in a dedicated module at the repository root. Each package should have its own `pyproject.toml` specifying its details and dependencies. For example, this repository includes the `aieng-topic-impl` package.
+
+If your repository contains multiple packages, link each one in the main `pyproject.toml` as shown below to ensure they are built and linked for local development:
+
+```toml
+[tool.uv.workspace]
+members = [
+  "aieng-topic-impl",
+]
+
+[tool.uv.sources]
+aieng-topic-impl = { workspace = true }
+```
+
+When testing packages, use pre-release versions (e.g., v0.1.0a1, v0.1.0a2, v0.1.0b1). After testing, update to a release version (e.g., v1.0.0) before publishing. Follow the [official versioning scheme](https://packaging.python.org/en/latest/discussions/versioning/).
+
+## Google Colab Integration (For Notebooks Only)
+
+Ensure Jupyter Notebooks are runnable on Google Colab. This may require installing your locally linked package and resolving dependency conflicts in the Colab environment.
+
+Add the following Markdown cell at the top of your notebook to enable opening it in Colab:
+
+```markdown
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VectorInstitute/<REPO_NAME>/blob/main/<PATH_TO_NOTEBOOK>)
+```
+
+Include a Python cell like the one below at the beginning of your notebook to customize it for Colab:
+
+```python
+import os
+
+if "COLAB_RELEASE_TAG" in os.environ:
+    # Running in Google Colab
+    # Install required dependencies
+    !pip3 install numpy==1.26.4 torchvision==0.16.2 aieng-topic-impl
+    # Uninstall conflicting dependencies
+    !pip3 uninstall --yes torchao torchaudio torchdata torchsummary torchtune
+```
+
+## Dockerization
+
+Dockerize your project to ensure portability and consistency across platforms. This also facilitates deployment on the AI Engineering Platform used in bootcamps and workshops.
+
+- Update the provided `Dockerfile` to suit your project’s needs.
+- Modify `scripts/start.sh` to reflect your setup steps. This script will run at container startup.
+- Update the `README.md` with instructions to build and start the Docker container.
+
+## GitHub Actions
+
+### Publish
+
+Use this GitHub Actions workflow to publish packages. Create a PyPI token and set the `PYPI_API_TOKEN` secret in your repository settings. To trigger the publish workflow, create a GitHub Release and push a new tag (e.g., `v0.1.0`).
+
+After publishing, test the package by installing it in a new virtual environment and performing a sanity check.

implementations/implementation_a/topic_a_a.ipynb

@@ -24,16 +24,6 @@
     "## Install implementation specific package for a topic"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e89d13c0-6d80-45ab-ba7e-32ffc3fdbae5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install aieng-topic-impl"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,

pyproject.toml

@@ -7,6 +7,7 @@ readme = "README.md"
 repository = "https://github.com/VectorInstitute/aieng-template-implementation"
 requires-python = ">=3.12"
 dependencies = [
+    "aieng-topic-impl",
     "jupyterlab>=4.4.2",
 ]
 
@@ -24,6 +25,14 @@ dev = [
     "ruff>=0.9.2",
 ]
 
+[tool.uv.workspace]
+members = [
+  "aieng-topic-impl",
+]
+
+[tool.uv.sources]
+aieng-topic-impl = { workspace = true }
+
 [tool.mypy]
 ignore_missing_imports = true
 install_types = true