Skip to content

Commit

Permalink
Improve installation documentation and clarify provider dependencies (#…
Browse files Browse the repository at this point in the history 
…1087)

* Updated documentation to include installation of provider packages

* Fixed trailing whitespace in doc update

* Updated README and User Docs for Installtion instructions

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* update documentation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113 pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: David L. Qiu <[email protected]>
  • Loading branch information
@srdas @pre-commit-ci @dlqqq
3 people authored Nov 6, 2024
1 parent 49709dc commit 71be3ce
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 40 deletions.
68 changes: 61 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
100 changes: 67 additions & 33 deletions docs/source/users/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit 71be3ce

Please sign in to comment.