Merge pull request #4 from cloudera/merge_2_28_3

Merge from JupyterAI v2_28_3

.github/workflows/e2e-tests.yml

@@ -2,13 +2,13 @@ name: E2E Tests
 
 # suppress warning raised by https://github.com/jupyter/jupyter_core/pull/292
 env:
-  JUPYTER_PLATFORM_DIRS: '1'
+  JUPYTER_PLATFORM_DIRS: "1"
 
 on:
   push:
     branches: main
   pull_request:
-    branches: '*'
+    branches: "*"
 
 jobs:
   e2e-tests:
@@ -41,17 +41,17 @@ jobs:
             ${{ github.workspace }}/pw-browsers
           key: ${{ runner.os }}-${{ hashFiles('packages/jupyter-ai/ui-tests/yarn.lock') }}
 
-      - name: Install browser
+      - name: Install Chromium
         working-directory: packages/jupyter-ai/ui-tests
         run: jlpm install-chromium
 
-      - name: Execute e2e tests
+      - name: Run E2E tests
         working-directory: packages/jupyter-ai/ui-tests
         run: jlpm test
 
-      - name: Upload Playwright Test report
+      - name: Upload Playwright test report
         if: always()
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: jupyter-ai-playwright-tests-linux
           path: |

.github/workflows/unit-tests.yml

@@ -1,4 +1,4 @@
-name: Python Unit Tests
+name: Python Tests
 
 # suppress warning raised by https://github.com/jupyter/jupyter_core/pull/292
 env:
@@ -12,19 +12,52 @@ on:
 
 jobs:
   unit-tests:
-    name: Linux
+    name: Unit tests (Python ${{ matrix.python-version }}, ${{ matrix.dependency-type }} dependencies)
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dependency-type: minimum
+            python-version: "3.9"
+          - dependency-type: standard
+            python-version: "3.12"
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Base Setup
         uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+        with:
+          python_version: ${{ matrix.python-version }}
+          dependency_type: ${{ matrix.dependency-type }}
 
       - name: Install extension dependencies and build the extension
         run: ./scripts/install.sh
 
+      - name: List installed versions
+        run: pip list
+
       - name: Execute unit tests
         run: |
           set -eux
           pytest -vv -r ap --cov jupyter_ai
+
+  typing-tests:
+    name: Typing test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Base Setup
+        uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+
+      - name: Install extension dependencies and build the extension
+        run: ./scripts/install.sh
+
+      - name: Run mypy
+        run: |
+          set -eux
+          mypy --version
+          mypy packages/jupyter-ai

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: end-of-file-fixer
       - id: check-case-conflict
@@ -18,7 +18,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.10.0
     hooks:
       - id: black
 
@@ -30,13 +30,13 @@ repos:
         files: \.py$
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.16.0
+    rev: v3.19.0
     hooks:
       - id: pyupgrade
         args: [--py37-plus]
 
   - repo: https://github.com/pycqa/flake8
-    rev: 7.1.0
+    rev: 7.1.1
     hooks:
       - id: flake8
         additional_dependencies:
@@ -48,7 +48,7 @@ repos:
         stages: [manual]
 
   - repo: https://github.com/sirosen/check-jsonschema
-    rev: 0.29.0
+    rev: 0.30.0
     hooks:
       - id: check-jsonschema
         name: "Check GitHub Workflows"

README.md

@@ -68,26 +68,80 @@ Below is a simplified overview of the installation and usage process.
 See [our official documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html)
 for details on installing and using Jupyter AI.
 
-### With pip
+We offer 3 different ways to install Jupyter AI. You can read through each
+section to pick the installation method that works best for you.
+
+1. Quick installation via `pip` (recommended)
+2. Minimal installation via `pip`
+3. Minimal installation via `conda`
+
+### Quick installation via `pip` (recommended)
 
 If you want to install both the `%%ai` magic and the JupyterLab extension, you can run:
 
-    $ pip install jupyter-ai
+    $ pip install jupyter-ai[all]
+
+Then, restart JupyterLab. This will install every optional dependency, which
+provides access to all models currently supported by `jupyter-ai`.
 
-If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, you can run:
+If you are not using JupyterLab and you only want to install the Jupyter AI
+`%%ai` magic, you can run:
 
-    $ pip install jupyter-ai-magics
+    $ pip install jupyter-ai-magics[all]
 
+`jupyter-ai` depends on `jupyter-ai-magics`, so installing `jupyter-ai`
+automatically installs `jupyter-ai-magics`.
 
-### With conda
+### Minimal installation via `pip`
+
+Most model providers in Jupyter AI require a specific dependency to be installed
+before they are available for use. These are called _provider dependencies_.
+Provider dependencies are optional to Jupyter AI, meaning that Jupyter AI can be
+installed with or without any provider dependencies installed. If a provider
+requires a dependency that is not installed, its models are not listed in the
+user interface which allows you to select a language model.
+
+To perform a minimal installation via `pip` without any provider dependencies,
+omit the `[all]` optional dependency group from the package name:
+
+```
+pip install jupyter-ai
+```
+
+By selectively installing provider dependencies, you can control which models
+are available in your Jupyter AI environment.
+
+For example, to install Jupyter AI with only added support for Anthropic models, run:
+
+```
+pip install jupyter-ai langchain-anthropic
+```
+
+For more information on model providers and which dependencies they require, see
+[the model provider table](https://jupyter-ai.readthedocs.io/en/latest/users/index.html#model-providers).
+
+### Minimal installation via `conda`
 
 As an alternative to using `pip`, you can install `jupyter-ai` using
 [Conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)
-from the `conda-forge` channel, using one of the following two commands:
+from the `conda-forge` channel:
 
-    $ conda install -c conda-forge jupyter-ai  # or,
     $ conda install conda-forge::jupyter-ai
 
+Most model providers in Jupyter AI require a specific _provider dependency_ to
+be installed before they are available for use. Provider dependencies are
+not installed when installing `jupyter-ai` from Conda Forge, and should be
+installed separately as needed.
+
+For example, to install Jupyter AI with only added support for OpenAI models, run:
+
+```
+conda install conda-forge::jupyter-ai conda-forge::langchain-openai
+```
+
+For more information on model providers and which dependencies they require, see
+[the model provider table](https://jupyter-ai.readthedocs.io/en/latest/users/index.html#model-providers).
+
 ## The `%%ai` magic command
 
 The `%%ai` magic works anywhere the IPython kernel runs, including JupyterLab, Jupyter Notebook, Google Colab, and Visual Studio Code.

docs/source/contributors/index.md

@@ -20,11 +20,11 @@ Issues and pull requests that violate the above principles may be declined. If y
 
 You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.12, including recent Windows, macOS, and Linux versions.
 
-Each Jupyter AI major version works with only one major version of JupyterLab. Jupyter AI 1.x supports JupyterLab 3.x, and Jupyter AI 2.x supports JupyterLab 4.x.
+You should have the newest supported version of JupyterLab installed.
 
-We highly recommend that you install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to start developing on Jupyter AI, especially if you are developing on macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.).
+We highly recommend that you install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to start contributing to Jupyter AI, especially if you are developing on macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.).
 
-You will need Node.js 18 to use Jupyter AI. Node.js 18.16.0 is known to work.
+You will need [a supported version of node.js](https://github.com/nodejs/release#release-schedule) to use Jupyter AI.
 
 :::{warning}
 :name: node-18-15