Backport PR jupyterlab#1087: Improve installation documentation and c…

…larify provider dependencies
meeseeksmachine · Nov 6, 2024 · a7289de · a7289de
1 parent a8be64f
commit a7289de
Show file tree

Hide file tree

Showing 2 changed files with 128 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -53,26 +53,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.

diff --git a/docs/source/users/index.md b/docs/source/users/index.md
@@ -79,62 +79,96 @@ classes in their code.
 
 ## Installation
 
-### Installation via `pip`
+### Setup: creating a Jupyter AI environment (recommended)
 
-To install the JupyterLab extension, you can run:
+Before installing Jupyter AI, we highly recommend first creating a separate
+Conda environment for Jupyter AI. This prevents the installation process from
+clobbering Python packages in your existing Python environment.
 
-```
-pip install jupyter-ai
-```
+To do so, install
+[conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)
+and create an environment that uses Python 3.12 and the latest version of
+JupyterLab:
 
-You may need to install third-party packages, for example, to use some model providers and some file formats with Jupyter AI. To handle all supported use cases, you can install every dependency, which will give you access to all models currently supported by `jupyter-ai`. To install every dependency, run the following command, and then restart JupyterLab:
+    $ conda create -n jupyter-ai python=3.12 jupyterlab
+    $ conda activate jupyter-ai
 
-```
-pip install jupyter-ai[all]
-```
+You can now choose how to install Jupyter AI.
 
-The latest major version of `jupyter-ai`, v2, only supports JupyterLab 4. If you
-need support for JupyterLab 3, you should install `jupyter-ai` v1 instead:
+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.
 
-```
-pip install jupyter-ai~=1.0
-```
+1. Quick installation via `pip` (recommended)
+2. Minimal installation via `pip`
+3. Minimal installation via `conda`
 
-If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, you can run:
+### Quick installation via `pip` (recommended)
 
-```
-$ pip install jupyter-ai-magics
-```
+If you want to install both the `%%ai` magic and the JupyterLab extension, you can run:
+
+    $ 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:
+
+    $ pip install jupyter-ai-magics[all]
 
 `jupyter-ai` depends on `jupyter-ai-magics`, so installing `jupyter-ai`
 automatically installs `jupyter-ai-magics`.
 
-### Installation via `pip` or `conda` in a Conda environment (recommended)
+### Minimal installation via `pip`
 
-We highly recommend installing both JupyterLab and Jupyter AI within an isolated
-Conda environment to avoid clobbering Python packages in your existing Python
-environment.
+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.
 
-First, install
-[conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)
-and create an environment that uses Python 3.12:
+To perform a minimal installation via `pip` without any provider dependencies,
+omit the `[all]` optional dependency group from the package name:
 
-    $ conda create -n jupyter-ai python=3.12
-    $ conda activate jupyter-ai
+```
+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:
 
-Then, use `conda` to install JupyterLab and Jupyter AI in this Conda environment.
+```
+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:
 
-    $ conda install -c conda-forge jupyter-ai  # or,
     $ conda install conda-forge::jupyter-ai
 
-When starting JupyterLab with Jupyter AI, make sure to activate the Conda
-environment first:
+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 activate jupyter-ai
-jupyter lab
+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).
+
 ## Uninstallation
 
 If you installed Jupyter AI using `pip`, to remove the extension, run: