feat: migrate from poetry-cookiecutter to substrate

.copier-answers.yml

@@ -0,0 +1,13 @@
+_commit: v1.1.0
+_src_path: gh:superlinear-ai/substrate
+author_email: [email protected]
+author_name: Laurent Sorber <[email protected]>
+project_description: RAGLite is a Python toolkit for Retrieval-Augmented Generation
+    (RAG) with PostgreSQL or SQLite.
+project_name: raglite
+project_type: package
+project_url: https://github.com/superlinear-ai/raglite
+python_version: '3.10'
+typing: strict
+with_conventional_commits: true
+with_typer_cli: true

.devcontainer/devcontainer.json

@@ -3,10 +3,20 @@
     "dockerComposeFile": "../docker-compose.yml",
     "service": "devcontainer",
     "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}/",
-    "remoteUser": "user",
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": {},
+        "ghcr.io/devcontainers-extra/features/starship": {}
+    },
     "overrideCommand": true,
-    "postStartCommand": "cp --update /opt/build/poetry/poetry.lock /workspaces/${localWorkspaceFolderBasename}/ && mkdir -p /workspaces/${localWorkspaceFolderBasename}/.git/hooks/ && cp --update /opt/build/git/* /workspaces/${localWorkspaceFolderBasename}/.git/hooks/",
+    "postCreateCommand": "echo 'eval \"$(starship init bash)\"' >> ~/.bashrc",
+    "postStartCommand": "uv sync --python ${PYTHON_VERSION:-3.10} ${RESOLUTION_STRATEGY:+--resolution $RESOLUTION_STRATEGY} --all-extras && pre-commit install --install-hooks",
     "customizations": {
+        "jetbrains": {
+            "backend": "PyCharm",
+            "plugins": [
+                "com.github.copilot"
+            ]
+        },
         "vscode": {
             "extensions": [
                 "charliermarsh.ruff",
@@ -41,7 +51,10 @@
                     100
                 ],
                 "files.autoSave": "onFocusChange",
+                "github.copilot.chat.agent.enabled": true,
+                "github.copilot.chat.edits.codesearch.enabled": true,
                 "github.copilot.chat.edits.enabled": true,
+                "github.copilot.nextEditSuggestions.enabled": true,
                 "jupyter.kernels.excludePythonEnvironments": [
                     "/usr/local/bin/python"
                 ],
@@ -52,16 +65,16 @@
                     "notebook.source.organizeImports": "explicit"
                 },
                 "notebook.formatOnSave.enabled": true,
-                "python.defaultInterpreterPath": "/opt/raglite-env/bin/python",
+                "python.defaultInterpreterPath": "/opt/venv/bin/python",
                 "python.terminal.activateEnvironment": false,
                 "python.testing.pytestEnabled": true,
                 "ruff.importStrategy": "fromEnvironment",
                 "ruff.logLevel": "warning",
-                "terminal.integrated.defaultProfile.linux": "zsh",
-                "terminal.integrated.profiles.linux": {
-                    "zsh": {
-                        "path": "/usr/bin/zsh"
-                    }
+                "terminal.integrated.env.linux": {
+                    "GIT_EDITOR": "code --wait"
+                },
+                "terminal.integrated.env.mac": {
+                    "GIT_EDITOR": "code --wait"
                 }
             }
         }

.dockerignore

@@ -3,3 +3,6 @@
 
 # Git
 .git/
+
+# Python
+.venv/

.github/workflows/publish.yml

@@ -7,21 +7,15 @@ on:
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
+    runs-on: ghcr.io/astral-sh/uv:3.10-bookworm
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.10"
-
-      - name: Install Poetry
-        run: pip install --no-input poetry
-
       - name: Publish package
         run: |
-          poetry config pypi-token.pypi "${{ secrets.POETRY_PYPI_TOKEN_PYPI }}"
-          poetry publish --build
+          uv build
+          uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}

.github/workflows/test.yml

@@ -15,8 +15,9 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
+        resolution-strategy: ["highest", "lowest-direct"]
 
-    name: Python ${{ matrix.python-version }}
+    name: Python ${{ matrix.python-version }} (resolution=${{ matrix.resolution-strategy }})
 
     steps:
       - name: Checkout
@@ -28,19 +29,19 @@ jobs:
           node-version: 23
 
       - name: Install @devcontainers/cli
-        run: npm install --location=global @devcontainers/cli@0.72.0
+        run: npm install --location=global @devcontainers/cli@0.73.0
 
       - name: Start Dev Container
         run: |
           git config --global init.defaultBranch main
-          PYTHON_VERSION=${{ matrix.python-version }} OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} devcontainer up --workspace-folder .
+          PYTHON_VERSION=${{ matrix.python-version }} OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} RESOLUTION_STRATEGY=${{ matrix.resolution-strategy }} devcontainer up --workspace-folder .
 
       - name: Lint package
         run: devcontainer exec --workspace-folder . poe lint
 
       - name: Test package
         run: devcontainer exec --workspace-folder . poe test
-
+        
       - name: Upload coverage
         uses: codecov/codecov-action@v5
         with:

.gitignore

@@ -7,7 +7,7 @@ chainlit.md
 htmlcov/
 reports/
 
-# cruft
+# Copier
 *.rej
 
 # Data
@@ -38,17 +38,16 @@ notebooks/
 # macOS
 .DS_Store
 
+# mise
+mise.local.toml
+
 # mypy
 .dmypy.json
 .mypy_cache/
 
 # Node.js
 node_modules/
 
-# Poetry
-.venv/
-dist/
-
 # PyCharm
 .idea/
 
@@ -60,7 +59,10 @@ dist/
 
 # Python
 __pycache__/
+*.egg-info/
 *.py[cdo]
+.venv/
+dist/
 
 # RAGLite
 *.db

.pre-commit-config.yaml

@@ -16,13 +16,15 @@ repos:
       - id: rst-inline-touching-normal
       - id: text-unicode-replacement-char
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
+        args: ["--maxkb=700"] 
       - id: check-ast
       - id: check-builtin-literals
       - id: check-case-conflict
       - id: check-docstring-first
+      - id: check-illegal-windows-names
       - id: check-json
       - id: check-merge-conflict
       - id: check-shebang-scripts-are-executable
@@ -51,6 +53,13 @@ repos:
         require_serial: true
         language: system
         stages: [commit-msg]
+      - id: uv-lock-check
+        name: uv lock check
+        entry: uv lock
+        args: ["--check"]
+        require_serial: true
+        language: system
+        pass_filenames: false
       - id: ruff-check
         name: ruff check
         entry: ruff check
@@ -65,17 +74,6 @@ repos:
         require_serial: true
         language: system
         types_or: [python, pyi]
-      - id: shellcheck
-        name: shellcheck
-        entry: shellcheck
-        args: [--check-sourced]
-        language: system
-        types: [shell]
-      - id: poetry-check
-        name: poetry check
-        entry: poetry check
-        language: system
-        pass_filenames: false
       - id: mypy
         name: mypy
         entry: mypy

Dockerfile

@@ -1,87 +1,65 @@
 # syntax=docker/dockerfile:1
 ARG PYTHON_VERSION=3.10
-FROM python:$PYTHON_VERSION-slim AS base
+FROM ghcr.io/astral-sh/uv:python$PYTHON_VERSION-bookworm AS dev
 
-# Remove docker-clean so we can keep the apt cache in Docker build cache.
-RUN rm /etc/apt/apt.conf.d/docker-clean
-
-# Configure Python to print tracebacks on crash [1], and to not buffer stdout and stderr [2].
-# [1] https://docs.python.org/3/using/cmdline.html#envvar-PYTHONFAULTHANDLER
-# [2] https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUNBUFFERED
-ENV PYTHONFAULTHANDLER 1
-ENV PYTHONUNBUFFERED 1
-
-# Create a non-root user and switch to it [1].
-# [1] https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user
-ARG UID=1000
-ARG GID=$UID
-RUN groupadd --gid $GID user && \
-    useradd --create-home --gid $GID --uid $UID user --no-log-init && \
-    chown user /opt/
-USER user
-
-# Create and activate a virtual environment.
-ENV VIRTUAL_ENV /opt/raglite-env
-ENV PATH $VIRTUAL_ENV/bin:$PATH
-RUN python -m venv $VIRTUAL_ENV
-
-# Set the working directory.
-WORKDIR /workspaces/raglite/
+# Create and activate a virtual environment [1].
+# [1] https://docs.astral.sh/uv/concepts/projects/config/#project-environment-path
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH=$VIRTUAL_ENV/bin:$PATH
+ENV UV_PROJECT_ENVIRONMENT=$VIRTUAL_ENV
 
+# Tell Git that the workspace is safe to avoid 'detected dubious ownership in repository' warnings.
+RUN git config --system --add safe.directory '*'
 
+# Configure the user's shell.
+RUN echo 'HISTFILE=~/.history/.bash_history' >> ~/.bashrc && \
+    echo 'bind "\"\e[A\": history-search-backward"' >> ~/.bashrc && \
+    echo 'bind "\"\e[B\": history-search-forward"' >> ~/.bashrc && \
+    mkdir ~/.history/
 
-FROM base AS poetry
+FROM python:$PYTHON_VERSION-slim AS app
 
-USER root
+# Configure Python to print tracebacks on crash [1], and to not buffer stdout and stderr [2].
+# [1] https://docs.python.org/3/using/cmdline.html#envvar-PYTHONFAULTHANDLER
+# [2] https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUNBUFFERED
+ENV PYTHONFAULTHANDLER=1
+ENV PYTHONUNBUFFERED=1
 
-# Install Poetry in separate venv so it doesn't pollute the main venv.
-ENV POETRY_VERSION 1.8.0
-ENV POETRY_VIRTUAL_ENV /opt/poetry-env
-RUN --mount=type=cache,target=/root/.cache/pip/ \
-    python -m venv $POETRY_VIRTUAL_ENV && \
-    $POETRY_VIRTUAL_ENV/bin/pip install poetry~=$POETRY_VERSION && \
-    ln -s $POETRY_VIRTUAL_ENV/bin/poetry /usr/local/bin/poetry
+# Remove docker-clean so we can manage the apt cache with the Docker build cache.
+RUN rm /etc/apt/apt.conf.d/docker-clean
 
 # Install compilers that may be required for certain packages or platforms.
 RUN --mount=type=cache,target=/var/cache/apt/ \
     --mount=type=cache,target=/var/lib/apt/ \
     apt-get update && \
     apt-get install --no-install-recommends --yes build-essential
 
+# Create a non-root user and switch to it [1].
+# [1] https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user
+ARG UID=1000
+ARG GID=$UID
+RUN groupadd --gid $GID user && \
+    useradd --create-home --gid $GID --uid $UID user --no-log-init
 USER user
 
-# Install the run time Python dependencies in the virtual environment.
-COPY --chown=user:user poetry.lock* pyproject.toml /workspaces/raglite/
-RUN mkdir -p /home/user/.cache/pypoetry/ && mkdir -p /home/user/.config/pypoetry/ && \
-    mkdir -p src/raglite/ && touch src/raglite/__init__.py && touch README.md
-RUN --mount=type=cache,uid=$UID,gid=$GID,target=/home/user/.cache/pypoetry/ \
-    poetry install --only main --all-extras --no-interaction
-
-
-
-FROM poetry AS dev
-
-# Install development tools: curl, git, gpg, ssh, starship, sudo, vim, and zsh.
-USER root
-RUN --mount=type=cache,target=/var/cache/apt/ \
-    --mount=type=cache,target=/var/lib/apt/ \
-    apt-get update && \
-    apt-get install --no-install-recommends --yes curl git gnupg ssh sudo vim zsh && \
-    sh -c "$(curl -fsSL https://starship.rs/install.sh)" -- "--yes" && \
-    usermod --shell /usr/bin/zsh user && \
-    echo 'user ALL=(root) NOPASSWD:ALL' > /etc/sudoers.d/user && chmod 0440 /etc/sudoers.d/user
-RUN git config --system --add safe.directory '*'
-USER user
-
-# Install the development Python dependencies in the virtual environment.
-RUN --mount=type=cache,uid=$UID,gid=$GID,target=/home/user/.cache/pypoetry/ \
-    poetry install --all-extras --no-interaction
+# Set the working directory.
+WORKDIR /workspaces/raglite/
 
-# Persist output generated during docker build so that we can restore it in the dev container.
-COPY --chown=user:user .pre-commit-config.yaml /workspaces/raglite/
-RUN mkdir -p /opt/build/poetry/ && cp poetry.lock /opt/build/poetry/ && \
-    git init && pre-commit install --install-hooks && \
-    mkdir -p /opt/build/git/ && cp .git/hooks/commit-msg .git/hooks/pre-commit /opt/build/git/
+# Copy the app source code to the working directory.
+COPY --chown=user:user . .
+
+# Install the application and its dependencies [1].
+# [1] https://docs.astral.sh/uv/guides/integration/docker/#optimizations
+RUN --mount=type=cache,uid=$UID,gid=$GID,target=/home/user/.cache/uv \
+    --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
+    uv sync \
+    --all-extras \
+    --compile-bytecode \
+    --frozen \
+    --link-mode copy \
+    --no-dev \
+    --no-editable \
+    --python-preference only-system
 
 # Configure the non-root user's shell.
 ENV ANTIDOTE_VERSION 1.8.6
@@ -99,3 +77,7 @@ RUN git clone --branch v$ANTIDOTE_VERSION --depth=1 https://github.com/mattmc3/a
     echo 'bindkey "^[[B" history-beginning-search-forward' >> ~/.zshrc && \
     mkdir ~/.history/ && \
     zsh -c 'source ~/.zshrc'
+
+# Expose the app.
+ENTRYPOINT ["/workspaces/raglite/.venv/bin/poe"]
+CMD ["serve"]